pax_global_header00006660000000000000000000000064152410365230014513gustar00rootroot0000000000000052 comment=079611b654ad89afd9c3c3a1796d64bdd6a6b340 .clang-format000066400000000000000000000001651524103652300134340ustar00rootroot00000000000000--- Language: Cpp BasedOnStyle: Google # Always use `T* p`. DerivePointerAlignment: false PointerAlignment: Left ... .github/000077500000000000000000000000001524103652300124175ustar00rootroot00000000000000.github/dependabot.yml000066400000000000000000000004121524103652300152440ustar00rootroot00000000000000version: 2 updates: - package-ecosystem: "bazel" directory: "/src" target-branch: "master" schedule: interval: "weekly" - package-ecosystem: "github-actions" directory: "/" target-branch: "master" schedule: interval: "weekly" .github/workflows/000077500000000000000000000000001524103652300144545ustar00rootroot00000000000000.github/workflows/build.yml000066400000000000000000000221621524103652300163010ustar00rootroot00000000000000name: build and test on: pull_request: push: release: types: - released workflow_dispatch: concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} cancel-in-progress: true permissions: read-all jobs: cmake: strategy: matrix: runs-on: - ubuntu-22.04 - ubuntu-latest - ubuntu-22.04-arm - ubuntu-24.04-arm # Standard (free) macOS runners. # https://docs.github.com/en/actions/reference/runners/github-hosted-runners#standard-github-hosted-runners-for-public-repositories - macos-14 # AArch64 - macos-15 # AArch64 - macos-26 # AArch64 - macos-15-intel # x86-64 - macos-26-intel # x86-64 fail-fast: false runs-on: ${{ matrix.runs-on }} timeout-minutes: 15 steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - name: Set NUM_CORES run: | NUM_CORES=$(getconf _NPROCESSORS_ONLN) echo "NUM_CORES=$NUM_CORES" >> $GITHUB_ENV echo "Detected $NUM_CORES cores" - name: Setup ccache uses: hendrikmuhs/ccache-action@d62db5f07c26379fc4b4e0916f098a92573c3b03 # v1.2.23 with: key: ${{ github.job }}-${{ matrix.runs-on }} - name: Install dependencies (macOS) if: runner.os == 'macOS' run: brew install swig - run: mkdir build - run: > cmake -DWITH_PYTHON=ON -DWITH_PYTHON_LIMITED_API=${{ !startsWith(matrix.runs-on, 'ubuntu-22') && 'ON' || 'OFF' }} -DFETCH_ABSEIL=ON -DCMAKE_BUILD_TYPE=Dev -DCMAKE_CXX_STANDARD=17 -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache .. working-directory: build/ - run: cmake --build . --parallel ${{ env.NUM_CORES }} working-directory: build/ - if: always() run: | set -u # Join one-regex-per-line list (same alternation as a single POSIX ERE). # macOS doesn't support long options. FLAKY="$(paste -s -d '|' ../flaky_tests.txt)" ctest --parallel ${{ env.NUM_CORES }} --output-on-failure \ --exclude-regex "${FLAKY}" ctest --parallel ${{ env.NUM_CORES }} --output-on-failure \ --tests-regex "${FLAKY}" \ --repeat until-pass:3 working-directory: build/ cmake-big-endian: runs-on: ubuntu-24.04-arm timeout-minutes: 15 env: ARM_TOOLCHAIN_VERSION: "13.3.rel1" steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - name: Set NUM_CORES run: | NUM_CORES=$(getconf _NPROCESSORS_ONLN) echo "NUM_CORES=$NUM_CORES" >> $GITHUB_ENV echo "Detected $NUM_CORES cores" - name: Install QEMU user-mode run: sudo apt-get update && sudo apt-get install -y qemu-user - name: Download Arm GNU Toolchain run: | TARBALL="arm-gnu-toolchain-${ARM_TOOLCHAIN_VERSION}-aarch64-aarch64_be-none-linux-gnu.tar.xz" URL="https://developer.arm.com/-/media/Files/downloads/gnu/${ARM_TOOLCHAIN_VERSION}/binrel/${TARBALL}" wget -q "$URL" echo "46e8e8a573766f761efe7a16240bc2355b67cb30fab7ecc508b03f36c3034290 $TARBALL" | sha256sum --check tar xf "$TARBALL" -C /opt TOOLCHAIN_DIR="/opt/arm-gnu-toolchain-${ARM_TOOLCHAIN_VERSION}-aarch64-aarch64_be-none-linux-gnu" echo "${TOOLCHAIN_DIR}/bin" >> $GITHUB_PATH echo "TOOLCHAIN_DIR=${TOOLCHAIN_DIR}" >> $GITHUB_ENV - name: Create CMake toolchain file run: | cat > toolchain-aarch64_be.cmake << 'EOF' set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64_be-none-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64_be-none-linux-gnu-g++) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) EOF - run: mkdir build - run: > cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-aarch64_be.cmake -DCMAKE_CROSSCOMPILING_EMULATOR="qemu-aarch64_be;-L;${TOOLCHAIN_DIR}/aarch64_be-none-linux-gnu/libc" -DWITH_PYTHON=OFF -DFETCH_ABSEIL=ON -DSKIP_OPENSSL_TESTS=ON -DCMAKE_BUILD_TYPE=Dev -DCMAKE_CXX_STANDARD=17 .. working-directory: build/ - run: cmake --build . --parallel ${NUM_CORES} working-directory: build/ - if: always() name: Run tests run: | set -u # Known failures due to unimplemented big-endian encoding/decoding. EXCLUDE="EncodedS2PointVectorTest\.(Empty|OnePoint|AllExceptionsBlock|RoundtripEncodingFast)" EXCLUDE+="|EncodedS2ShapeIndex\.(OneEdge|RegularLoops|OverlappingPointClouds|OverlappingPolylines|OverlappingLoops|JavaByteCompatibility)" EXCLUDE+="|S2LaxPolygonShape\.(EmptyPolygon|FullPolygon|ManyLoopPolygon|InvertedLoops|S2CoderWorks)" EXCLUDE+="|S2LaxPolygonShapeTest\.BadLoopOffsets" EXCLUDE+="|S2LaxPolylineShape\.S2CoderWorks" EXCLUDE+="|S2Point\.CoderWorks" EXCLUDE+="|S2RegionEncodeDecodeTest\.S2(Loop|Polygon|Polyline)" EXCLUDE+="|FastEncodeTaggedShapes\.MixedShapes" EXCLUDE+="|DecodeTaggedShapes\.(DecodeFromByteString|DecodeFromEncoded)" EXCLUDE+="|OutgoingEdgeButNoIncomingEdge" FLAKY="$(paste --serial --delimiters='|' ../flaky_tests.txt)" ctest --parallel ${NUM_CORES} --output-on-failure \ --exclude-regex "${EXCLUDE}|${FLAKY}" ctest --parallel ${NUM_CORES} --output-on-failure \ --tests-regex "${FLAKY}" \ --exclude-regex "${EXCLUDE}" \ --repeat until-pass:3 working-directory: build/ bazel: strategy: matrix: runs-on: - ubuntu-latest - macos-latest fail-fast: false runs-on: ${{ matrix.runs-on }} timeout-minutes: 15 # We would like to test on the oldest and newest supported. # https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md # https://bazel.build/release#support-matrix # It's not clear how to do that since bazelisk has some magic to pick a # bazel version. steps: - name: Checkout repository uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - name: Setup Bazel uses: bazel-contrib/setup-bazel@c5acdfb288317d0b5c0bbd7a396a3dc868bb0f86 # 0.19.0 with: # Avoid downloading Bazel every time. bazelisk-cache: true # Share caches between workflows. disk-cache: true repository-cache: true # The Bazel workspace is in the src directory. module-root: src - name: Build and Test run: | bazel test \ --config=ci \ --config=dev \ --keep_going \ --test_verbose_timeout_warnings \ //... working-directory: src python: timeout-minutes: 10 strategy: matrix: runs-on: - ubuntu-latest - ubuntu-24.04-arm # Standard (free) macOS runners. # TODO: Expand to the full set of 5 macOS runners if this won't # cause trouble for the PyPI upload. - macos-15 # AArch64 - macos-15-intel # x86-64 fail-fast: false runs-on: ${{ matrix.runs-on }} steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: fetch-tags: true persist-credentials: false - uses: pypa/cibuildwheel@294735312765b09d24a2fbec22660ce817587d55 # v4.1.0 with: package-dir: ./ output-dir: dist/ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: dist-${{ matrix.runs-on }} path: ./dist/ python-publish: if: (github.event_name == 'release') && (github.event.action == 'released') needs: [python] timeout-minutes: 30 runs-on: ubuntu-latest permissions: id-token: write attestations: write # Requires environment protection rules in GitHub Settings: # Settings > Environments > pypi > Add required reviewers environment: name: pypi url: https://pypi.org/p/s2geometry steps: - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: pattern: dist* path: dist/ merge-multiple: true - uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1 with: subject-path: "dist/*" # To upload to PyPI without a token, add this workflow file as a Trusted Publisher in the project settings on the PyPI website - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0 .github/workflows/lint.yml000066400000000000000000000036121524103652300161470ustar00rootroot00000000000000name: lint on: pull_request: push: branches: - master workflow_dispatch: concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} cancel-in-progress: true permissions: contents: read jobs: lint: runs-on: ubuntu-latest timeout-minutes: 1 steps: # Default clone depth is enough here: we only run buildifier on the # checked-out tree (no PR-range git diffs in this workflow). - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - name: Install buildifier run: | set -u BUILDIFIER_VERSION=8.5.1 BUILDIFIER_SHA256=887377fc64d23a850f4d18a077b5db05b19913f4b99b270d193f3c7334b5a9a7 BUILDIFIER_DL=/tmp/buildifier curl -fsSL -o "${BUILDIFIER_DL}" \ "https://github.com/bazelbuild/buildtools/releases/download/v${BUILDIFIER_VERSION}/buildifier-linux-amd64" echo "${BUILDIFIER_SHA256} ${BUILDIFIER_DL}" | sha256sum --check - chmod +x "${BUILDIFIER_DL}" sudo mv "${BUILDIFIER_DL}" /usr/local/bin/buildifier - name: Check Starlark / BUILD formatting (buildifier) run: buildifier -r -mode=check . - name: Install keep-sorted run: | set -u KEEPSORTED_VERSION=0.8.0 KEEPSORTED_SHA256=0d9801785ac354232ea754bbfd8cc204a5e255905e14bcbff5fe8733e4dbd85c KEEPSORTED_DL=/tmp/keep-sorted curl -fsSL -o "${KEEPSORTED_DL}" \ "https://github.com/google/keep-sorted/releases/download/v${KEEPSORTED_VERSION}/keep-sorted_linux" echo "${KEEPSORTED_SHA256} ${KEEPSORTED_DL}" | sha256sum --check - chmod +x "${KEEPSORTED_DL}" sudo mv "${KEEPSORTED_DL}" /usr/local/bin/keep-sorted - name: Check keep-sorted run: git ls-files -z | xargs -0 keep-sorted --mode=lint .gitignore000066400000000000000000000001041524103652300130420ustar00rootroot00000000000000bazel-* build/ MODULE.bazel.lock # compiled module src/s2geometry* AUTHORS000066400000000000000000000007411524103652300121310ustar00rootroot00000000000000# This is the official list of glog authors for copyright purposes. # This file is distinct from the CONTRIBUTORS files. # See the latter for an explanation. # # Names should be added to this file as: # Name or Organization # The email address is not required for organizations. # # Please keep the list sorted. Aurora Innovation Dan Larkin-York Google Inc. Koordinates Limited Mike Playle Tiago Brito CMakeLists.txt000066400000000000000000000726251524103652300136330ustar00rootroot00000000000000cmake_minimum_required(VERSION 3.18) # avoids error: aligned allocation function of type 'void *(std::size_t, std::align_val_t)' is only available on macOS 10.13 or newer # see https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md#macos set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13" CACHE STRING "Minimum macOS version") # Custom "Dev" build type: optimized but without -DNDEBUG so that asserts remain # active. Use with -DCMAKE_BUILD_TYPE=Dev. Defining the _INIT variables before # project() seeds the cache via the same mechanism CMake uses for the built-in # build types (Debug, Release, etc.). set(CMAKE_CXX_FLAGS_DEV_INIT "-O1") project(s2-geometry VERSION 0.12.0) include(CMakeDependentOption) include(CheckCXXCompilerFlag) include(FeatureSummary) include(FetchContent) include(FindPackageHandleStandardArgs) include(GNUInstallDirs) set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # Avoid "Policy CMP0042 is not set" warning on macOS. if (APPLE) set(CMAKE_MACOSX_RPATH TRUE) endif() # s2geometry needs to use the same C++ standard that absl used to avoid # undefined symbol errors since ABSL_HAVE_STD_STRING_VIEW etc will # end up defined differently. There is probably a better way to achieve # this than assuming what absl used. We require at least C++17. # Using CACHE allows the user to override the default. set(CMAKE_CXX_STANDARD 17 CACHE STRING "The C++ standard to build with") set(CMAKE_CXX_STANDARD_REQUIRED ON) # No compiler-specific extensions, i.e. -std=c++17, not -std=gnu++17. set(CMAKE_CXX_EXTENSIONS OFF) option(BUILD_SHARED_LIBS "Build shared libraries instead of static." ON) add_feature_info(SHARED_LIBS BUILD_SHARED_LIBS "builds shared libraries instead of static.") option(BUILD_EXAMPLES "Build s2 documentation examples." ON) option(BUILD_TESTS "Build s2 unittests." ON) option(WITH_PYTHON "Add python interface" OFF) # Requires SWIG >= 4.2 and CMake >= 3.26. option(WITH_PYTHON_LIMITED_API "Use Python Limited API for SWIG" OFF) add_feature_info(PYTHON WITH_PYTHON "provides python interface to S2") option(S2_USE_SYSTEM_INCLUDES "Silence warnings in s2 headers by marking them as SYSTEM includes." OFF) add_feature_info(S2_USE_SYSTEM_INCLUDES S2_USE_SYSTEM_INCLUDES "Silence warnings in s2 headers by marking them as SYSTEM includes.") # when s2geometry is included as subproject (i.e. using add_subdirectory(s2geometry)) # in the source tree of a project that uses it, install rules are disabled. if(NOT CMAKE_SOURCE_DIR STREQUAL PROJECT_SOURCE_DIR) option(S2_ENABLE_INSTALL "Enable install rule" OFF) else() option(S2_ENABLE_INSTALL "Enable install rule" ON) endif() feature_summary(WHAT ALL) # Don't output anything for LOG(INFO). add_definitions(-DABSL_MIN_LOG_LEVEL=1) # If we already have abseil we don't need to find it, for an example: # add_subdirectory(absl-submbodule) # add_subdirectory(s2-submodule) if (NOT TARGET absl::base) option(FETCH_ABSEIL "Download and build abseil-cpp" OFF) if (FETCH_ABSEIL) message(STATUS "Downloading and building abseil-cpp...") FetchContent_Declare( absl URL https://github.com/abseil/abseil-cpp/archive/refs/tags/20260526.0.zip DOWNLOAD_EXTRACT_TIMESTAMP TRUE ) set(ABSL_PROPAGATE_CXX_STD ON CACHE BOOL "" FORCE) set(ABSL_ENABLE_INSTALL ON CACHE BOOL "" FORCE) set(BUILD_TESTING OFF CACHE BOOL "" FORCE) set(CMAKE_POSITION_INDEPENDENT_CODE ON CACHE BOOL "" FORCE) FetchContent_MakeAvailable(absl) else() find_package(absl REQUIRED) endif() endif() # pthreads isn't used directly, but this is still required for std::thread. find_package(Threads REQUIRED) if (NOT TARGET absl::vlog_is_on) message(FATAL_ERROR "Could not find absl vlog module. Are you using an older version?") endif() if (WITH_PYTHON) # Use Python3_ROOT_DIR to help find python3, if the correct location is not # being found by default. if (WITH_PYTHON_LIMITED_API) # Development.SABIModule requires CMake 3.26; be explicit. cmake_minimum_required(VERSION 3.26) find_package(Python3 3.10 COMPONENTS Interpreter Development.SABIModule REQUIRED) # SWIG requires 4.2 for stable ABI support. # https://www.swig.org/Doc4.2/Python.html#Python_stable_abi find_package(SWIG 4.2 REQUIRED) else() find_package(Python3 3.10 COMPONENTS Interpreter Development.Module REQUIRED) find_package(SWIG 4.0 REQUIRED) endif() endif() if (MSVC) # Use unsigned characters add_definitions(-J) # Make sure cmath header defines things like M_PI add_definitions(-D_USE_MATH_DEFINES) # Make sure Windows doesn't define min/max macros that interfere with STL add_definitions(-DNOMINMAX) else() # Avoid megabytes of warnings like: # util/math/vector.h:178:16: warning: optimization attribute on # ‘double sqrt(double)’ follows definition but the attribute doesn’t # match [-Wattributes] add_definitions(-Wno-attributes) add_definitions(-Wno-deprecated-declarations) add_definitions(-Wno-nullability-completeness) # Suppress noisy AArch64 ABI notes about parameter passing changes in # GCC 10.1. Irrelevant since we don't mix objects from old compilers. # TODO: Use check_cxx_compiler_flag(-Wno-psabi) to guard this. add_compile_options(-Wno-psabi) # Some files use sized deallocation, which should be enabled by # default for C++14 and later. There appears to be a bug with clang # < 19 causing this not to be enabled. # https://github.com/google/s2geometry/issues/411#issuecomment-2726949607 # This can be removed when clang19 is the minimum supported version. add_compile_options(-fsized-deallocation) endif() # If OpenSSL is installed in a non-standard location, configure with # something like: # OPENSSL_ROOT_DIR=/usr/local/opt/openssl cmake .. # TODO: Unused? bignum_test uses target_include_directories instead. include_directories(${OPENSSL_INCLUDE_DIR}) if (WITH_PYTHON) include_directories(${Python3_INCLUDE_DIRS}) endif() include_directories(src) add_library(s2 src/s2/base/malloc_extension.cc src/s2/encoded_s2cell_id_vector.cc src/s2/encoded_s2point_vector.cc src/s2/encoded_s2shape_index.cc src/s2/encoded_string_vector.cc src/s2/id_set_lexicon.cc src/s2/internal/s2incident_edge_tracker.cc src/s2/internal/s2index_cell_data.cc src/s2/mutable_s2shape_index.cc src/s2/r2rect.cc src/s2/s1angle.cc src/s2/s1chord_angle.cc src/s2/s1interval.cc src/s2/s2boolean_operation.cc src/s2/s2buffer_operation.cc src/s2/s2builder.cc src/s2/s2builder_graph.cc src/s2/s2builderutil_closed_set_normalizer.cc src/s2/s2builderutil_find_polygon_degeneracies.cc src/s2/s2builderutil_get_snapped_winding_delta.cc src/s2/s2builderutil_lax_polygon_layer.cc src/s2/s2builderutil_lax_polyline_layer.cc src/s2/s2builderutil_s2point_vector_layer.cc src/s2/s2builderutil_s2polygon_layer.cc src/s2/s2builderutil_s2polyline_layer.cc src/s2/s2builderutil_s2polyline_vector_layer.cc src/s2/s2builderutil_snap_functions.cc src/s2/s2cap.cc src/s2/s2cell.cc src/s2/s2cell_id.cc src/s2/s2cell_index.cc src/s2/s2cell_union.cc src/s2/s2centroids.cc src/s2/s2chain_interpolation_query.cc src/s2/s2closest_cell_query.cc src/s2/s2closest_edge_query.cc src/s2/s2closest_point_query.cc src/s2/s2contains_vertex_query.cc src/s2/s2convex_hull_query.cc src/s2/s2coords.cc src/s2/s2crossing_edge_query.cc src/s2/s2debug.cc src/s2/s2density_tree.cc src/s2/s2earth.cc src/s2/s2edge_clipping.cc src/s2/s2edge_crosser.cc src/s2/s2edge_crossings.cc src/s2/s2edge_distances.cc src/s2/s2edge_tessellator.cc src/s2/s2error.cc src/s2/s2fractal.cc src/s2/s2furthest_edge_query.cc src/s2/s2hausdorff_distance_query.cc src/s2/s2latlng.cc src/s2/s2latlng_rect.cc src/s2/s2latlng_rect_bounder.cc src/s2/s2lax_loop_shape.cc src/s2/s2lax_polygon_shape.cc src/s2/s2lax_polyline_shape.cc src/s2/s2loop.cc src/s2/s2loop_measures.cc src/s2/s2max_distance_targets.cc src/s2/s2measures.cc src/s2/s2memory_tracker.cc src/s2/s2metrics.cc src/s2/s2min_distance_targets.cc src/s2/s2padded_cell.cc src/s2/s2point_compression.cc src/s2/s2point_region.cc src/s2/s2pointutil.cc src/s2/s2polygon.cc src/s2/s2polyline.cc src/s2/s2polyline_alignment.cc src/s2/s2polyline_measures.cc src/s2/s2polyline_simplifier.cc src/s2/s2predicates.cc src/s2/s2projections.cc src/s2/s2r2rect.cc src/s2/s2random.cc src/s2/s2region_coverer.cc src/s2/s2region_intersection.cc src/s2/s2region_sharder.cc src/s2/s2region_term_indexer.cc src/s2/s2region_union.cc src/s2/s2shape_index.cc src/s2/s2shape_index_buffered_region.cc src/s2/s2shape_index_measures.cc src/s2/s2shape_measures.cc src/s2/s2shape_nesting_query.cc src/s2/s2shapeutil_build_polygon_boundaries.cc src/s2/s2shapeutil_coding.cc src/s2/s2shapeutil_contains_brute_force.cc src/s2/s2shapeutil_conversion.cc src/s2/s2shapeutil_count_vertices.cc src/s2/s2shapeutil_edge_iterator.cc src/s2/s2shapeutil_edge_wrap.cc src/s2/s2shapeutil_get_reference_point.cc src/s2/s2shapeutil_visit_crossing_edge_pairs.cc src/s2/s2text_format.cc src/s2/s2wedge_relations.cc src/s2/s2winding_operation.cc src/s2/util/bits/bit-interleave.cc src/s2/util/coding/coder.cc src/s2/util/coding/varint.cc src/s2/util/math/exactfloat/bignum.cc src/s2/util/math/exactfloat/exactfloat.cc src/s2/util/math/mathutil.cc src/s2/util/units/length-units.cc) target_link_libraries( s2 absl::absl_vlog_is_on absl::base absl::btree absl::check absl::config absl::core_headers absl::dynamic_annotations absl::endian absl::fixed_array absl::flags absl::flat_hash_map absl::flat_hash_set absl::hash absl::inlined_vector absl::int128 absl::log absl::log_severity absl::memory absl::span absl::status absl::statusor absl::str_format absl::strings absl::type_traits absl::utility absl::vlog_is_on ${CMAKE_THREAD_LIBS_INIT}) # Allow other CMake projects to use this one with: # list(APPEND CMAKE_MODULE_PATH "/third_party/cmake") # add_subdirectory( s2geometry) # target_link_libraries( s2) if (S2_USE_SYSTEM_INCLUDES) target_include_directories(s2 SYSTEM PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src) else () target_include_directories(s2 PUBLIC $ $) endif () # Add version information to the target set_target_properties(s2 PROPERTIES SOVERSION ${PROJECT_VERSION_MAJOR} VERSION ${PROJECT_VERSION}) if (BUILD_TESTS) # Used to avoid otherwise unneeded dependency for AArch64-BE cross-compilation. # Currently only bignum_test requires OpenSSL. option(SKIP_OPENSSL_TESTS "Skip tests that require OpenSSL." OFF) if (NOT SKIP_OPENSSL_TESTS) find_package(OpenSSL REQUIRED) endif() # We could use a pre-installed benchmark with # `find_package(benchmark QUIET)` then, `if (NOT benchmark_FOUND)`, but # that could run into trouble if benchmark isn't PIC, but # s2geometry is. benchmark isn't PIC by default, but s2geometry is # when building a shared lib. Always build benchmark for simplicity. message(STATUS "Downloading and building benchmark...") FetchContent_Declare( benchmark # https://github.com/google/benchmark/releases/tag/v1.9.4 URL https://github.com/google/benchmark/archive/eddb0241389718a23a42db6af5f0164b6e0139af.zip DOWNLOAD_EXTRACT_TIMESTAMP TRUE ) # Don't install benchmark when s2geometry is installed. set(BENCHMARK_ENABLE_INSTALL OFF CACHE BOOL "" FORCE) set(BENCHMARK_ENABLE_TESTING OFF CACHE BOOL "" FORCE) FetchContent_MakeAvailable(benchmark) # https://google.github.io/googletest/quickstart-cmake.html#set-up-a-project message(STATUS "Downloading googletest...") FetchContent_Declare( googletest # https://github.com/google/googletest/releases/tag/v1.17.0 URL https://github.com/google/googletest/archive/52eb8108c5bdec04579160ae17225d66034bd723.zip DOWNLOAD_EXTRACT_TIMESTAMP TRUE ) FetchContent_MakeAvailable(googletest) include(GoogleTest) add_library(s2testing STATIC src/s2/gmock_matchers.cc src/s2/s2builderutil_testing.cc src/s2/s2shapeutil_testing.cc src/s2/s2testing.cc src/s2/thread_testing.cc) target_link_libraries( s2testing absl::check absl::flags absl::log absl::memory absl::strings GTest::gmock) add_library(test_main OBJECT src/s2/testing/test_main.cc) target_link_libraries(test_main PRIVATE benchmark::benchmark PRIVATE GTest::gtest) set(S2TestFiles src/s2/encoded_s2cell_id_vector_test.cc src/s2/encoded_s2point_vector_test.cc src/s2/encoded_s2shape_index_test.cc src/s2/encoded_string_vector_test.cc src/s2/encoded_uint_vector_test.cc src/s2/gmock_matchers_test.cc src/s2/id_set_lexicon_test.cc src/s2/internal/s2disjoint_set_test.cc src/s2/internal/s2index_cell_data_test.cc src/s2/mutable_s2shape_index_test.cc src/s2/r1interval_test.cc src/s2/r2rect_test.cc src/s2/s1angle_test.cc src/s2/s1chord_angle_test.cc src/s2/s1interval_test.cc src/s2/s2boolean_operation_test.cc src/s2/s2buffer_operation_test.cc src/s2/s2builder_graph_test.cc src/s2/s2builder_test.cc src/s2/s2builderutil_closed_set_normalizer_test.cc src/s2/s2builderutil_find_polygon_degeneracies_test.cc src/s2/s2builderutil_get_snapped_winding_delta_test.cc src/s2/s2builderutil_lax_polygon_layer_test.cc src/s2/s2builderutil_lax_polyline_layer_test.cc src/s2/s2builderutil_s2point_vector_layer_test.cc src/s2/s2builderutil_s2polygon_layer_test.cc src/s2/s2builderutil_s2polyline_layer_test.cc src/s2/s2builderutil_s2polyline_vector_layer_test.cc src/s2/s2builderutil_snap_functions_test.cc src/s2/s2builderutil_testing_test.cc src/s2/s2cap_test.cc src/s2/s2cell_id_test.cc src/s2/s2cell_index_test.cc src/s2/s2cell_iterator_join_test.cc src/s2/s2cell_iterator_testing_test.cc src/s2/s2cell_range_iterator_test.cc src/s2/s2cell_test.cc src/s2/s2cell_union_test.cc src/s2/s2centroids_test.cc src/s2/s2chain_interpolation_query_test.cc src/s2/s2closest_cell_query_base_test.cc src/s2/s2closest_cell_query_test.cc src/s2/s2closest_edge_query_base_test.cc src/s2/s2closest_edge_query_test.cc src/s2/s2closest_point_query_base_test.cc src/s2/s2closest_point_query_test.cc src/s2/s2contains_point_query_test.cc src/s2/s2contains_vertex_query_test.cc src/s2/s2convex_hull_query_test.cc src/s2/s2coords_test.cc src/s2/s2crossing_edge_query_test.cc src/s2/s2density_tree_test.cc src/s2/s2earth_test.cc src/s2/s2edge_clipping_test.cc src/s2/s2edge_crosser_test.cc src/s2/s2edge_crossings_test.cc src/s2/s2edge_distances_test.cc src/s2/s2edge_tessellator_test.cc src/s2/s2edge_vector_shape_test.cc src/s2/s2error_test.cc src/s2/s2fractal_test.cc src/s2/s2furthest_edge_query_test.cc src/s2/s2hausdorff_distance_query_test.cc src/s2/s2latlng_rect_bounder_test.cc src/s2/s2latlng_rect_test.cc src/s2/s2latlng_test.cc src/s2/s2lax_loop_shape_test.cc src/s2/s2lax_polygon_shape_test.cc src/s2/s2lax_polyline_shape_test.cc src/s2/s2loop_measures_test.cc src/s2/s2loop_test.cc src/s2/s2max_distance_targets_test.cc src/s2/s2measures_test.cc src/s2/s2memory_tracker_test.cc src/s2/s2metrics_test.cc src/s2/s2min_distance_targets_test.cc src/s2/s2padded_cell_test.cc src/s2/s2point_compression_test.cc src/s2/s2point_index_test.cc src/s2/s2point_region_test.cc src/s2/s2point_test.cc src/s2/s2point_vector_shape_test.cc src/s2/s2pointutil_test.cc src/s2/s2polygon_test.cc src/s2/s2polyline_alignment_test.cc src/s2/s2polyline_measures_test.cc src/s2/s2polyline_simplifier_test.cc src/s2/s2polyline_test.cc src/s2/s2predicates_test.cc src/s2/s2projections_test.cc src/s2/s2r2rect_test.cc src/s2/s2random_test.cc src/s2/s2region_coverer_test.cc src/s2/s2region_sharder_test.cc src/s2/s2region_term_indexer_test.cc src/s2/s2region_test.cc src/s2/s2region_union_test.cc src/s2/s2shape_index_buffered_region_test.cc src/s2/s2shape_index_measures_test.cc src/s2/s2shape_index_region_test.cc src/s2/s2shape_index_test.cc src/s2/s2shape_measures_test.cc src/s2/s2shape_nesting_query_test.cc src/s2/s2shapeutil_build_polygon_boundaries_test.cc src/s2/s2shapeutil_coding_test.cc src/s2/s2shapeutil_contains_brute_force_test.cc src/s2/s2shapeutil_conversion_test.cc src/s2/s2shapeutil_count_edges_test.cc src/s2/s2shapeutil_count_vertices_test.cc src/s2/s2shapeutil_edge_iterator_test.cc src/s2/s2shapeutil_edge_wrap_test.cc src/s2/s2shapeutil_get_reference_point_test.cc src/s2/s2shapeutil_shape_edge_id_test.cc src/s2/s2shapeutil_visit_crossing_edge_pairs_test.cc src/s2/s2text_format_test.cc src/s2/s2validation_query_test.cc src/s2/s2wedge_relations_test.cc src/s2/s2winding_operation_test.cc src/s2/s2wrapped_shape_test.cc src/s2/sequence_lexicon_test.cc src/s2/value_lexicon_test.cc src/s2/util/math/exactfloat/exactfloat_test.cc src/s2/util/math/exactfloat/exactfloat_underflow_test.cc) if (NOT SKIP_OPENSSL_TESTS) list(APPEND S2TestFiles src/s2/util/math/exactfloat/bignum_test.cc) endif() enable_testing() foreach (test_cc ${S2TestFiles}) get_filename_component(test ${test_cc} NAME_WE) add_executable(${test} ${test_cc}) target_link_libraries( ${test} s2testing s2 absl::base absl::btree absl::check absl::core_headers absl::flags absl::flags_reflection absl::log absl::memory absl::random_random absl::span absl::status absl::strings absl::synchronization benchmark::benchmark test_main) # Compared to `add_test()`, displays progress and success/failure of each # test case rather than just the binary, so we see # `S2Cell.TestSubdivide ... PASSED`. Also lists disabled tests. gtest_discover_tests(${test}) endforeach() if (NOT SKIP_OPENSSL_TESTS) target_link_libraries( bignum_test ${OPENSSL_LIBRARIES}) target_include_directories( bignum_test PRIVATE ${OPENSSL_INCLUDE_DIR}) endif() endif() if (BUILD_EXAMPLES AND TARGET s2testing) add_subdirectory("doc/examples" examples) endif() if (WITH_PYTHON) add_subdirectory("src/python" python) endif() if(S2_ENABLE_INSTALL) # We don't need to install all headers, only those # transitively included by s2 headers we are exporting. install(FILES src/s2/_fp_contract_off.h src/s2/encoded_s2cell_id_vector.h src/s2/encoded_s2point_vector.h src/s2/encoded_s2shape_index.h src/s2/encoded_string_vector.h src/s2/encoded_uint_vector.h src/s2/gmock_matchers.h src/s2/id_set_lexicon.h src/s2/mutable_s2shape_index.h src/s2/r1interval.h src/s2/r2.h src/s2/r2rect.h src/s2/s1angle.h src/s2/s1chord_angle.h src/s2/s1interval.h src/s2/s2boolean_operation.h src/s2/s2buffer_operation.h src/s2/s2builder.h src/s2/s2builder_graph.h src/s2/s2builder_layer.h src/s2/s2builderutil_closed_set_normalizer.h src/s2/s2builderutil_find_polygon_degeneracies.h src/s2/s2builderutil_get_snapped_winding_delta.h src/s2/s2builderutil_graph_shape.h src/s2/s2builderutil_lax_polygon_layer.h src/s2/s2builderutil_lax_polyline_layer.h src/s2/s2builderutil_s2point_vector_layer.h src/s2/s2builderutil_s2polygon_layer.h src/s2/s2builderutil_s2polyline_layer.h src/s2/s2builderutil_s2polyline_vector_layer.h src/s2/s2builderutil_snap_functions.h src/s2/s2builderutil_testing.h src/s2/s2cap.h src/s2/s2cell.h src/s2/s2cell_id.h src/s2/s2cell_index.h src/s2/s2cell_iterator.h src/s2/s2cell_iterator_join.h src/s2/s2cell_range_iterator.h src/s2/s2cell_union.h src/s2/s2centroids.h src/s2/s2chain_interpolation_query.h src/s2/s2closest_cell_query.h src/s2/s2closest_cell_query_base.h src/s2/s2closest_edge_query.h src/s2/s2closest_edge_query_base.h src/s2/s2closest_point_query.h src/s2/s2closest_point_query_base.h src/s2/s2coder.h src/s2/s2contains_point_query.h src/s2/s2contains_vertex_query.h src/s2/s2convex_hull_query.h src/s2/s2coords.h src/s2/s2coords_internal.h src/s2/s2crossing_edge_query.h src/s2/s2debug.h src/s2/s2density_tree.h src/s2/s2density_tree_internal.h src/s2/s2distance_target.h src/s2/s2earth.h src/s2/s2edge_clipping.h src/s2/s2edge_crosser.h src/s2/s2edge_crossings.h src/s2/s2edge_crossings_internal.h src/s2/s2edge_distances.h src/s2/s2edge_tessellator.h src/s2/s2edge_vector_shape.h src/s2/s2error.h src/s2/s2fractal.h src/s2/s2furthest_edge_query.h src/s2/s2hausdorff_distance_query.h src/s2/s2latlng.h src/s2/s2latlng_rect.h src/s2/s2latlng_rect_bounder.h src/s2/s2lax_loop_shape.h src/s2/s2lax_polygon_shape.h src/s2/s2lax_polyline_shape.h src/s2/s2loop.h src/s2/s2loop_measures.h src/s2/s2max_distance_targets.h src/s2/s2measures.h src/s2/s2memory_tracker.h src/s2/s2metrics.h src/s2/s2min_distance_targets.h src/s2/s2padded_cell.h src/s2/s2point.h src/s2/s2point_array.h src/s2/s2point_compression.h src/s2/s2point_index.h src/s2/s2point_region.h src/s2/s2point_span.h src/s2/s2point_vector_shape.h src/s2/s2pointutil.h src/s2/s2polygon.h src/s2/s2polyline.h src/s2/s2polyline_alignment.h src/s2/s2polyline_measures.h src/s2/s2polyline_simplifier.h src/s2/s2predicates.h src/s2/s2predicates_internal.h src/s2/s2projections.h src/s2/s2r2rect.h src/s2/s2random.h src/s2/s2region.h src/s2/s2region_coverer.h src/s2/s2region_intersection.h src/s2/s2region_sharder.h src/s2/s2region_term_indexer.h src/s2/s2region_union.h src/s2/s2shape.h src/s2/s2shape.h src/s2/s2shape_index.h src/s2/s2shape_index_buffered_region.h src/s2/s2shape_index_region.h src/s2/s2shape_measures.h src/s2/s2shape_nesting_query.h src/s2/s2shapeutil_build_polygon_boundaries.h src/s2/s2shapeutil_coding.h src/s2/s2shapeutil_contains_brute_force.h src/s2/s2shapeutil_conversion.h src/s2/s2shapeutil_count_edges.h src/s2/s2shapeutil_count_vertices.h src/s2/s2shapeutil_edge_iterator.h src/s2/s2shapeutil_edge_wrap.h src/s2/s2shapeutil_get_reference_point.h src/s2/s2shapeutil_shape_edge.h src/s2/s2shapeutil_shape_edge_id.h src/s2/s2shapeutil_testing.h src/s2/s2shapeutil_visit_crossing_edge_pairs.h src/s2/s2testing.h src/s2/s2text_format.h src/s2/s2validation_query.h src/s2/s2wedge_relations.h src/s2/s2winding_operation.h src/s2/s2wrapped_shape.h src/s2/sequence_lexicon.h src/s2/thread_testing.h src/s2/value_lexicon.h DESTINATION include/s2) install(FILES src/s2/internal/s2disjoint_set.h src/s2/internal/s2incident_edge_tracker.h src/s2/internal/s2index_cell_data.h src/s2/internal/s2meta.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/internal") install(FILES src/s2/base/casts.h src/s2/base/log_severity.h src/s2/base/malloc_extension.h src/s2/base/spinlock.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/base") install(FILES src/s2/testing/gtest_prod.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/testing") install(FILES src/s2/util/bitmap/bitmap.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/bitmap") install(FILES src/s2/util/coding/coder.h src/s2/util/coding/varint.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/coding") install(FILES src/s2/util/endian/endian.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/endian") install(FILES src/s2/util/gtl/compact_array.h src/s2/util/gtl/container_logging.h src/s2/util/gtl/dense_hash_set.h src/s2/util/gtl/densehashtable.h src/s2/util/gtl/hashtable_common.h src/s2/util/gtl/requires.h src/s2/util/gtl/unaligned.h src/s2/util/gtl/value_or_die.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/gtl") install(FILES src/s2/util/hash/mix.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/hash") install(FILES src/s2/util/math/mathutil.h src/s2/util/math/matrix3x3.h src/s2/util/math/vector.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/math") install(FILES src/s2/util/math/exactfloat/bignum.h src/s2/util/math/exactfloat/exactfloat.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/math/exactfloat") install(FILES src/s2/util/units/length-units.h src/s2/util/units/physical-units.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/s2/util/units") if (BUILD_TESTS) set(S2_TARGETS s2 s2testing) else() set(S2_TARGETS s2) endif() install(TARGETS ${S2_TARGETS} RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}" ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}" LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}") # Create an export type "s2Targets" detailing the targetable artifacts created # by this project. install(TARGETS s2 EXPORT s2Targets) # Install the export targets as a CMake config file in the share/s2 folder so # that they can referenced by downstream projects as `s2::s2` after a # successful `find_package` call. install(EXPORT s2Targets NAMESPACE s2:: FILE s2Targets.cmake DESTINATION share/s2/) endif() # S2_ENABLE_INSTALL include(CMakePackageConfigHelpers) # Generate the config file that includes the exports. configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/s2Config.cmake" INSTALL_DESTINATION "share/s2/" NO_SET_AND_CHECK_MACRO NO_CHECK_REQUIRED_COMPONENTS_MACRO) write_basic_package_version_file( "${CMAKE_CURRENT_BINARY_DIR}/s2ConfigVersion.cmake" VERSION ${PROJECT_VERSION} COMPATIBILITY SameMinorVersion) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/s2Config.cmake ${CMAKE_CURRENT_BINARY_DIR}/s2ConfigVersion.cmake DESTINATION "share/s2/") CONTRIBUTING.md000066400000000000000000000061631524103652300133160ustar00rootroot00000000000000# How to contribute # We'd love to accept your patches and contributions to this project. There are a just a few small guidelines you need to follow. ## Contributor License Agreement ## Contributions to any Google project must be accompanied by a Contributor License Agreement. This is not a copyright **assignment**, it simply gives Google permission to use and redistribute your contributions as part of the project. * If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an [individual CLA][]. * If you work for a company that wants to allow you to contribute your work, then you'll need to sign a [corporate CLA][]. You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again. [individual CLA]: https://developers.google.com/open-source/cla/individual [corporate CLA]: https://developers.google.com/open-source/cla/corporate Once your CLA is submitted (or if you already submitted one for another Google project), make a commit adding yourself to the [AUTHORS][] and [CONTRIBUTORS][] files. This commit can be part of your first [pull request][]. [AUTHORS]: AUTHORS [CONTRIBUTORS]: CONTRIBUTORS ## Submitting a patch ## 1. It's generally best to start by opening a new issue describing the bug or feature you're intending to fix. Even if you think it's relatively minor, it's helpful to know what people are working on. Mention in the initial issue that you are planning to work on that bug or feature so that it can be assigned to you. 1. Follow the normal process of [forking][] the project, and setup a new branch to work in. It's important that each group of changes be done in separate branches in order to ensure that a pull request only includes the commits related to that bug or feature. 1. Do your best to have [well-formed commit messages][] with a [good description][] for each change. This provides consistency throughout the project, and ensures that commit messages are able to be formatted properly by various git tools. 1. Keep PRs [small and focused][] on a single issue. Do not make unrelated changes in the same PR "because you're there"; this includes reformatting of code, whether automatically or manually. 1. Finally, push the commits to your fork and submit a [pull request][]. [forking]: https://help.github.com/articles/fork-a-repo [well-formed commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html [good description]: https://google.github.io/eng-practices/review/developer/cl-descriptions.html [pull request]: https://help.github.com/articles/creating-a-pull-request [small and focused]: https://google.github.io/eng-practices/review/developer/small-cls.html ## Style ## Contributions should follow the [Google C++ Style Guide]. Code may be [formatted] with `git clang-format`. [Google C++ Style Guide]: http://google.github.io/styleguide/cppguide.html [formatted]: http://google.github.io/styleguide/cppguide.html#Formatting CONTRIBUTORS000066400000000000000000000024201524103652300127350ustar00rootroot00000000000000# People who have agreed to one of the CLAs and can contribute patches. # The AUTHORS file lists the copyright holders; this file # lists people. For example, Google employees are listed here # but not in AUTHORS, because Google holds the copyright. # # Names should be added to this file only after verifying that # the individual or the individual's organization has agreed to # the appropriate Contributor License Agreement, found here: # # https://developers.google.com/open-source/cla/individual # https://developers.google.com/open-source/cla/corporate # # The agreement for individuals can be filled out on the web. # # When adding J Random Contributor's name to this file, # either J's name or J's organization's name should be # added to the AUTHORS file, depending on whether the # individual or corporate CLA was used. # # Names should be added to this file as: # Name # # Please keep the list sorted. Dan Larkin-York David Eustis Eric Veach Jesse Rosenstock Julien Basch Mike Playle Phil Elson Robert Coup Tiago Brito Zachary Burnett Config.cmake.in000066400000000000000000000002051524103652300136700ustar00rootroot00000000000000@PACKAGE_INIT@ include(CMakeFindDependencyMacro) find_dependency(absl CONFIG) include("${CMAKE_CURRENT_LIST_DIR}/s2Targets.cmake") LICENSE000066400000000000000000000261361524103652300120740ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. NOTICE000066400000000000000000000002241524103652300117610ustar00rootroot00000000000000S2 Geometry Library Copyright 2017 Google Inc. All Rights Reserved. This product includes software developed at Google (https://www.google.com/). README.md000066400000000000000000000161631524103652300123450ustar00rootroot00000000000000# S2 Geometry Library ## Overview This is a package for manipulating geometric shapes. Unlike many geometry libraries, S2 is primarily designed to work with _spherical geometry_, i.e., shapes drawn on a sphere rather than on a planar 2D map. This makes it especially suitable for working with geographic data. If you want to learn more about the library, start by reading the [overview](http://s2geometry.io/about/overview) and [quick start document](http://s2geometry.io/devguide/cpp/quickstart), then read the introduction to the [basic types](http://s2geometry.io/devguide/basic_types). S2 documentation can be found on [s2geometry.io](http://s2geometry.io). ## API/ABI Stability Note that all [releases](https://github.com/google/s2geometry/releases) are version 0.x, so there are [no API or ABI stability guarantees](https://semver.org/#spec-item-4). Starting with 1.0 we will adhere to [SemVer](https://semver.org/) and follow the [Google OSS breaking change policy](https://opensource.google/documentation/policies/library-breaking-change) The Python API is particularly unstable, and it is planned that the SWIGged API will be replaced by a pybind11 version with more Pythonic names and more complete functionality. ## Requirements for End Users using Bazel ## Build This bazel build requires [Bazel 8 or newer](https://github.com/google/oss-policies-info/blob/main/foundational-cxx-support-matrix.md#compilers-tools-build-systems). Builds were tested using C++20 as set in .bazelrc. This setup relies on abseil-cpp and googletest from the bazel central repository as set in MODULE.bazel. To build and test using bazel, from within s2geometry/src, run: `bazel test "//:*"` To build the libary without testing, from within s2geometry/src, run: `bazel build //:s2` ## Status All tests enumerated in the BUILD.bazel file pass on x86 machines. On Apple M1, s2loop_measures_test fails due to a 6% excess accumlated error. This issue may require revision of boringssl or exactfloat. ## Requirements for End Users using CMake * We aim to support all platforms supported by the [Google foundational C++ support policy](https://opensource.google/documentation/policies/cplusplus-support) * [CMake](http://www.cmake.org/) >= 3.22 * A C++ compiler with C++17 support, such as [g++ >= 7.5](https://gcc.gnu.org/) or [clang >= 14.0.0](https://clang.llvm.org/) * [Abseil](https://github.com/abseil/abseil-cpp) LTS [`20260526`](https://github.com/abseil/abseil-cpp/releases/tag/20260526.0) (standard library extensions). This exact version must be used. * [googletest testing framework >= 1.10](https://github.com/google/googletest) (to build tests and example programs, optional) * [OpenSSL](https://github.com/openssl/openssl) (for its bignum library) On Ubuntu, all of these other than abseil can be installed via apt-get: ``` sudo apt-get install cmake libssl-dev ``` abseil-cpp may need to be installed from source if an LTS release is not packaged for the platform. See the use of `-DCMAKE_PREFIX_PATH` in the [build instructions below](#building). On macOS, use [MacPorts](http://www.macports.org/) or [Homebrew](http://brew.sh/). For MacPorts: ``` sudo port install cmake abseil gtest openssl ``` ## Build and Install You may either download the source as a ZIP archive, or [clone the git repository](https://help.github.com/articles/cloning-a-repository/). ### Via ZIP archive Download [ZIP file](https://github.com/google/s2geometry/archive/master.zip) ``` cd [parent of directory where you want to put S2] unzip [path to ZIP file]/s2geometry-master.zip cd s2geometry-master ``` ### Via `git clone` ``` cd [parent of directory where you want to put S2] git clone https://github.com/google/s2geometry.git cd s2geometry ``` ### Building First, [install Abseil](https://github.com/abseil/abseil-cpp/blob/master/CMake/README.md#traditional-cmake-set-up). It must be configured with `-DCMAKE_POSITION_INDEPENDENT_CODE=ON`. s2geometry must be configured to use the same C++ version that abseil uses. The easiest way to achieve this is to pass `-DCMAKE_CXX_STANDARD=17` to `cmake` when compiling both abseil and s2geometry. From the appropriate directory depending on how you got the source: ``` mkdir build cd build # You can use -DBUILD_TESTS=no to skip tests. # Use the same CMAKE_CXX_STANDARD value that was used with absl. cmake -DBUILD_TESTS=yes -DCMAKE_PREFIX_PATH=/path/to/absl/install -DCMAKE_CXX_STANDARD=17 .. make -j $(nproc) make test ARGS="-j$(nproc)" # If -DBUILD_TESTS=yes was used above. sudo make install ``` On macOS, `sysctl -n hw.logicalcpu` is the equivalent of `nproc`. Disable building of shared libraries with `-DBUILD_SHARED_LIBS=OFF`. Enable the python interface with `-DWITH_PYTHON=ON`. # For Testing If BUILD_TESTS is 'on' (the default), then OpenSSL must be available to build some tests: * [OpenSSL](https://github.com/openssl/openssl) (for its bignum library) If OpenSSL is installed in a non-standard location set `OPENSSL_ROOT_DIR` before running configure, for example on macOS: ``` OPENSSL_ROOT_DIR=/opt/homebrew/Cellar/openssl@3/3.1.0 cmake -DCMAKE_PREFIX_PATH=/opt/homebrew -DCMAKE_CXX_STANDARD=17 ``` ## Installing From `build` subdirectory: ``` make install ``` Prefix it with `sudo` if needed: ``` sudo make install ``` _NOTE_: There is not `uninstall` target but `install_manifest.txt` may be helpful. All files will be installed at location specified in `CMAKE_INSTALL_PREFIX` variable. Several suffix variables used for some file groups: Variable | Default | Description -------- | ------- | ----------- `CMAKE_INSTALL_INCLUDEDIR` | `include` | For header files `CMAKE_INSTALL_BINDIR` | `bin` | For executables and `*.dll` files on `DLL`-based platforms `CMAKE_INSTALL_LIBDIR` | `lib` | For library files (`*.so`, `*.a`, `*.lib` etc) If needed set this variables on command line as `cmake` arguments with `-D` prefix or edit from `build` subdirectory: ``` make edit_cache ``` For more info read: [The CMake Cache](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#the-cmake-cache). ## Python If you want the Python interface, you need to run cmake using `-DWITH_PYTHON=ON`. You will also need to install the following dependencies: * [SWIG 4](https://github.com/swig/swig) (for Python support, optional) * python3-dev (for Python support, optional) which can be installed via ``` sudo apt-get install swig python3-dev ``` or on macOS: ``` sudo port install swig ``` SWIG version 4.0 is required. [Python 3.10 is required](https://github.com/google/oss-policies-info/blob/main/foundational-python-support-matrix.md). ### Creating wheels First, make a virtual environment and install `build` into it: ``` python3 -m venv venv source venv/bin/activate pip install build ``` Then build the wheel: ``` python -m build ``` The resulting wheel will be in the `dist` directory. > If OpenSSL is in a non-standard location make sure to set `OPENSSL_ROOT_DIR`; > see above for more information. ## Other S2 implementations * [Go](https://github.com/golang/geo) (Approximately 40% complete.) * [Java](https://github.com/google/s2-geometry-library-java) ## Disclaimer This is not an official Google product. doc/000077500000000000000000000000001524103652300116245ustar00rootroot00000000000000doc/design/000077500000000000000000000000001524103652300130755ustar00rootroot00000000000000doc/design/images/000077500000000000000000000000001524103652300143425ustar00rootroot00000000000000doc/design/images/s2shapeindexva--39vql36wm1d.png000066400000000000000000000176221524103652300217770ustar00rootroot00000000000000PNG  IHDR~@7 cHRMz&u0`:pQ<bKGDtIME urIDATxwT'kK$dcv m ';I{fg;g&gs:v&b@Ih_J%Uݺ2?#nխ1Hu}e\uA!c~_!Ƣ'CO!B: ?!t ~B0a( !PBHBieᲆ2 ŧW'=rSF˘\R e#X[.cdQ/{QB..0_\AGO6KS 񟷗q' IhJ:CB˭tܝ`dF1NEp+p@}LΤ'笖tVpwFcg8"^[sOeG`C6qoVtȧCȧH{ZS%6+Gy֎OX =VP(ȥ8>)0Rجc"~?t_m|9RD>)h_! 6-=%c# "+0=N*I/D&z;.]a@""bC1ěQ `Y !  W0+DoWda[+%y|t&z;*uҸqggx,+_!8©(2#Dz]L/=-cfYA:D.FO* kN7l|u{C:<૑u*82j9;L[_j@HF^=OcYX/'`zE謌ylT bp`g@Ǹ|AU0RZhb4P'sk[j8xxG~_i.ڑ"7Um3 _ޞ>!w-yC7 PLP<)+Vx"|@M/+ϻE8% =EKГLnBU|z߭[:Rɿ_>l?4/ffiaYw4{cf{fD>B.iq]|uk?:ġ,-O: {epan ʇpr0n (/M.(h#Jywd tCm3YP1:?| ާޖ ?,@5\~茶+;H_|Na3] ݔ`{-"7z]D,|}{Pc^G߃ߴ]\/bxBk x_ىfX"~?~M8Z2=`WL+&+=]amELg`\?!kO.( Zh.o^oG-7'vbC>8D"ܹ%]\*La_G[sɹtCO| bg7 ج8q07SE3qmt?x]/eji>Vo60}a{,X3^wцh7X,(+W/uu/ -$ p_슢۸1 c DwBm'ݽ% É>NÂ8Zb`*.:ʹ,,UV֨?`w6p둌\8GW;uѦ8賊fw{f݃( rM4Qe6dwp/avx`VBEO=GXj7.ڱ2&TcamBfX ?{'[Ǩ[𛶋1Q@.7uEY>nk>`np0[*PXvb32NEpp&mRzYmo&\˛sٺ3U\P5D"N e^yKfxdK|JK rI oEh>J+60>["p$ IL\က|:B]-f~ GyWQ6 %:;)4^v/prφlMCځX.*XXi>{,o:u HPtWR-2*cve뇽)'*bA LJҾ7aZ /U0*B ^u k:M&pj0j %/setoƙ!o&zw%,mZ8y0ԫuvqݖSiFA} drRO&~sk-IhSK.L,LGvS-y`_]ް'Mo!ڠuAD}M//?czEkJOE)K"za|}Ofv=۔h34sP  !p`gFo!@ }]W\~?wЈ{Qg7dLK!-BX9 oծ?j.MyL8T4h eȆ!Ըēt( ). 4ZuOWqwџ3:4=El3]z%,TJ=2"(h wT_k~I`! 4Mn4OIjt}\ -@c VMK(+1w+t=ΊMLK!-LYKBM mァ9>jnx(-%&6f>ѻ P!m4⯏BY;32CaCi"tso*}8rFBYD$AulcODEu$z^bxZIU "HG*£7! :Ş?0Whlڲ>DCIVrgT@3jkiPunZ`yPH9A,sg絆^d=Pn}HN=Ic=aA#t06XA(P xC6!r>RryVl3`Z4nlDžnبh&4ӆP iW4"X$C" dTԄ{DX[! t}$-lC]mtʪ y6!m 껱g  &]q}]}}NB)6fV4٬ߗ LέCV-0` 8ă!ۉ~=b박ߗFA rBfb"d*lףS3-a+p] 4//h :_GtĢuʞ2iRw_\=׶ˋ-}+ךl\2;e;0m'v`Ok9pl@^V@뺸`:l&2a?{'K@OE;uϥcUt߈!A;6T RZV,~N,P~3qZ'ub!7ڃzJ Av%ty|gc c+Su O?<>鰕=2mWK d#FEC(X4谕=0mƖp +f)}:&@㗊n"eHNhn'4Ât,MDQ-#To$v12Caڸ2C &g P:/4BJ= 5:SF[ݰqet CT!Ox2# 4E7R7eUבE ߗC&"ʴBTTBY:#ixJ=0C`bE|V 'xO06وhF1Y pXZWtБ!>9ᾰߗCvɳb&"`|:HPnC`i]Rin# IEDC"aΥ(5|7!%$L, uE. rQ,,B\V~q1|Bx騀;SSGPU0uHv e^Z.Z4V2Y-u,XD@HJOZ._LG6N=#M[AVm$Tt/@_&`r # ,,11Wħv#o',\Q,f.LFx\t1vZ6cerrEB!S<`<91eդ=Mꨢqd8A.!"X4Q(X.ꘘ-\!IwmFDȊA_Gn!N?#!`G;lB@EzhG!F*&.u&3!Fޗz"* r,vX ualۅT:.6L}لy'"4Ղ{8n5DžTy+ۅ?,Dž]\1 ,c ,8 AH bȧK0@<*<)? eˁVCy+Mˆpl6kN5-ہe\V_$x<ˀ٧,8  Xgs xx9<ǀ　C|u/BiSaeA$P/DžmWGʮ°86,@k;lkkmò]N5YıXBpluqѴ$@0̃e]8Exǀ(a B!c\u_X [-c49 09W֙a綅2 e ̳"5BHMB !PBH'CO!B: ?!t ~B0a( !T ':%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--4jb6xfakep.png000066400000000000000000000460111524103652300220150ustar00rootroot00000000000000PNG  IHDR&# cHRMz&u0`:pQ<bKGDtIME uJIDATx_u9  sDʒ%{;Oܻw?sb~vgxmY"Ŝ cuW/`ʢ+" u IuAAA6XAEA*XAEA*XAEA*XAEA*xeL&[jSi*T[JGCV4vpJ6|^~DE:/"u#IF A'.Oa2`|B z \.|n;nÆnC@UuMCn4 B!Si) #I/}l㴋(#y6&j\]벓H=kqmlbBMX xTrw.k1 09g 7gJ,9%c#b#D`ZSsE&l 3aMVv {vbNeZmemCQ~"7g˚5hGUNWHG}k:&U&s̾l NAHD`YNv%ʪ|pyCc>f[tΎM1"tk:V^c1B^ڿ e.ޮ*J-.\?e 7?Rxݣ:ƍS Um 0/&> +/gKܲA `sHLd]=[s:lԡ!˳d/ k 2|pD2%p=5x~:c{z$q9#֡ o_(}AX%XCQuNߪm0jP/vu߽r&OrxGڰR4w <}p- U ՈrBn|$Ѩ5Uչ: .G!+cD`sꌤCkF& /h*<ȡm)&0I˛ 4d\*u71V[%_WThvb; Ă;1!/ojkFGeng[D,u$W:\`vn{w3`~"C&N}.qqƦtIFU/ !=ki)l$IP5N %4Yg|o(ºJ5eÜP5+%&*|n^kMΡmI~uaj ? OQtel=(FW.QvWt>7Khu.sdm{-{xB/=ڊF"wCZmIp;vp;gJ +mYҟoe|aĚ݆ ,FLL^&WPwhUT =vc.c^Fn>k=V٦|ns$gg8%D<`j52%|MR+jMf[fx6l9qJ:tS UEnK^}v~'qPj=4KpF:N:!0gυaD;*MYXmsak B;LF{,vloUmظ4t݇SFGvGgb6b6/-i+dEoM usV吝hejCTSh4t:wZ,ZQa0!vKW֍Սo-49qBp:@O^/Yu&*F{"ܯSyH>]b|x\ݓ&派j4 !euX(ZhrsA&m'TE$UM2[H@2632Fᤇ-iDyﶳ>qaG!?jkLf?Ǝ!;}KEnee Eؔ tb_:#tw' mi4Ԛ W97QaSˁ {mwt8sxx[}JSMũnKZ.ȼwiH\ljE?hpW7>F +?y'\n/b sxk6t6\.s;l m4M'dQ5vMqnKR:Ӌ5[Fmٲ&o$Hho&~jCEctr۹&Ev_>?$2#tG*2\,sj|=0zh]cGSk¡m)S\]: a-\~vGE3DuM~Th4対4@CVWȔFiE 4Nf[LgeY'm0`8і4ar}|H.*ueCTn:֏t:;WJ}6ݪ<.;x4ͣ;yOԌҲiu7 UYټ?G)sFT'uf3x acsB-~5tDl J76:|~bz3;"/ZDs"+S56q`ELI; |xi!JK7i{7g`; &I E|um}>><QA}voӐ܋a+eƆdIѠl ]ۏ>ss+-Tʜ%IEGҢZw9LuGBCI1z8$Ʒc4_'_5ﾋ!|MtZ;aS "IĞ_?xKQNU]{ǒw)aaRp6 (?f۠5?{c<+?Lޜ Uە1w08ǥfr5z-69y%I0ַum 19W몛3%*޿Z2˘ qps>'.05ߒvK[Ѹ5ߤ?n ݆nT;I>;K>t]_:uF"澕?I8l+ZqDUveu2'bVhBc}>h}VzQvcA"|NDC q͙2#!>l]8Y\pCݣ;ÜQyP5 y^<C~͆aCtdE)+mJUBI*9 ])reΟ<%U,ypU^t[ }DDḍc;#R]*h^b!ٌmKM:ʑ-AltfxuƫoKqph[J͉E6C5[Y|Ay>T,tEQh2+z^IJsJC6Mk$Ij)IZ:U;=_<} Gײ(&Iu-]<߽4"&So:Op|gdUGs|u$A4o REqoI/NI Phpk]p8$v}!6~~!K%޿R6¯N/99[Hv,@̅>5r\b*; A5箄$׏G{iz@P>U$[n$?0@؀{y<ġw==^!Wjg=K|n;}n?+sG\=]x=Ҕ;6Mk'9: sL.TXÃ\Zܵ,x6LT8۝%͘+y+޾\%-םPXxɳbD+= ,.4k쨄7ɡC|4r72v/ϼ4ȫɖ9=!&3-S!S)y<>>Uο}Q o$H*̞.nl6j)ıd͟>dת\( DJSֈ/ca#Q~~|*߾X p||]|8z[d9hɝ#mB~01QmոPdUρi}\K4MhT\NT-^Fdv7d.xdW?ɒFA+⑸YlQTzA: Ld^(ZhH< t)ŐO!n̕k2X#3`tvM/Mc!>V1z"vZ#p o(a0,2䝶$h,Q5.CP+dE'VH˷5]tfIa2uC$b\ӱH&E z ̶\2=$Q/sb{"m=/Dh˩ϼ lq~OB;ق̙v"7ÆRupVTTUTMPWMVmLjvf ^ Mhڲm2>%_msnFl*Ee KD{^a]t[j #!<]vc)~`UUtTK4^qu,-.[㩞!86]Y)ӎ(nhf[E t#& aμEV4^;g|Ŏ(W|ILf*xfn̔I~߅iptڰ34]j(Pmi ~=C^FDDA>m4Jsg@C"b#I:G|Q7)ɤ#k{z`Y( ɨ \ea[$^sU1# qc|=~cnMz[R4 mhK,$w` 7@Mrr$c3l6ӄNe(i29v20W`mO.oK*$| $~}Fb &Q)|(aoAn e*:?eUӧ>*;7޿尮ݑ/L<Nw%Kڪ?7v/]S`~cߖ3QGv,bI vfK!5~2_h 8񹭝$o4ef˯O/ z}Oe9a';Yrek??(X(6zZJufrm6^ABx\6B>YVXn7kwyz$#^l3"9!~lɼ=MTJ 2DB %.~zUEճL2 {YK? ?(b@|ق@qp̻mUsUlv;K`gH Yp64[~bm#jpJ]&I 6tMûڿ$m)|lNX__9db\=ƗMU$E b;զ+,u\N:6mI˓a=h^8s:˗3` g2,Bl6A'B8|4^eS5ڝ&^ba/-=>й4hPvpc2bC;*c(ܜovzsm %"܇i; VڜϠ4\)1wl]'(W˲rmI"j*JXi㏟8qym|wO*df2^&k<k Og\vy8}2P+,D+$xjo?x<͵"ndƝS5W2sߑ`7 6l1z$Z œ4d UM,Ҕ5Q/XȃϳEQAQ7vKTk1_lX'0?mk ٬痧r޾\❫Ee}3B^H|n;Ȏz[ ng\.(:AjCxR', + ZɎ!HlVn3g"`]rGTuU8y"uE_SOO<>_oNܢ `ݱ fK!B[5MV;阗XKaRWsɅID<<&Php~c;Rͦ|帝6v8{ H%9[ *4e[7G&nV1d cXh(&#>^8:L뺻$A4&tsSB.J>'2f5s6/N0ٷAuؼy;2{Q_|jklJyHbYǍ{$TgxlgGVKNFG[] Auл+,jmZawm⨱EeK2_(XV1oXttˉk/c3YeoKZu?AVGX7".@6ź)Z +L~#CTO?>})>;>*9 :^:TMis5vm=af2,3Gan>U獾$w:m4b)L;3a**;,{),tRo)t3zavF4`"&ٜ?n&4\#$3_NKXux]/ ْZ:\.ĞCAQ4~~[ 2O4;#)EkyFA[kB2$_3ꪔ8l! 9HGѸpkMթEv,w} Ta ȖE`PkW݃kU_$B}Mó]n`Q&}7EZH`#ЂeKRwN]U`$x`K\Y3bo=feˌ rDCn_-?ac^l2_U=MF,&]0:ARt9jN]=趐WG3 prg]_>`H/6Sb/`oko:lu zV~bAuB"sy[[ ҷu$ M5):jx\E8i΅,²emU u9Jx/ʜYxv"~!ǁnC@QuJա\w%v GV}N$|'>R[jB8+ŽA*h+[zQq/]6^I. viʮ.ɑn|$lI&S .;fsMZ\.-}ڴE>Am ޹T❋%?e4elp+lx6Zmk k*!7hɡ-A\Z>Fq%X\]Ϟ'ZJO %>(+?0=I}1yF ^8eV9ۖ,VI?1mY\v` g®5]RWh688T>?Z:k7}}T'fxsa 㝝,صgx` <}$MaKtzu jAmDQՆm*m!Nݨ(읰NEB04Β61r(k/ޱhm}1u锪m";QHG\2A#2޿^0.aX^>Wac8j0?g?~;C[/~K zJ#[R5rzs>PnLu4}LgFcEn͕9婽1޾XB %t˔d&Sd/suk3EɴCY;#˳\YւuuhHj}"zXr6e["tsi6P>`|BA]q;q%@UAtMѨTE%v1u3t3]$=R!~ߺ}MivėهY6%=x\Hd se_8?PQ v-B~ZEp< Տ'|x\^/% m8w7'Eը۔jmL4C>vo 9?P4ʲ;H$Ix<-h`clIE*u0{W5tmBb!Bס\[sB>;m {8uM9b~"ZSE칾 ܁ WKbW-skSwyOO펆"wک4/0xjn vu!I )689^El rFhK:jzÉ |V?|{{9dr_~ig?sc 847MMhľFB,%IKm)ζhTN]RWUVO[V/桭a,&'7r>k'-gGU8>sT:cq/H#\ s `"Y5f*G9y}A߲4d@ep\a(X. EvDgxLrC]OJG}lh:Q5ng+Lgֿb{yz_c;#]^In7,laRES?C= ,!Atq̭ 2Gwn :,cJ]׹6U 8`Ho6:qci^9gNT,E88hmj`7c4m)ٰP+T]f+7:u)N?;:z+6^G|AdNg)V;FGXO<6]t%tRmu,[+]gMOZ۹ - -jf_Z~AuڊJ,b4ewݮKl[2$Wʐ %ܘ-vDN|pmH1c$3(?z7wI}ǂ\pIDnq,À%ێh2afH=kܪri$Bb/GwFy TSɗz@qd,!\]̧:SXU;fV ?Z=NN_1p}h_Ts7BMfk2ǶIӶCcAʍ?|;ßcf뜾Q![0 0ϟ'bWhutvnvZpc|o?P|ut,6HFx-Wnre2gҾVX\Eoex|o*`@)1a>0ZG]ztPi*?0O?1 u *taP[S V~='3M d؋nʌȿX//J0w7h/[ 9ClLtΐ2a[nEJR`9??ȡm)vocqd,桝iDdEc:פ?n7r"^*uRM^'xlW>TN$Q >>ǖ~s6pz|w[|,VlJx:?~o-:8@7LQW뎁t|~EјȴYw쎰E,gz%tPUE n7W>ӖH\5tFRO6q{Ib9:~.W>eB~džO{e }.o0"4JI8vZ"ܑa>>^P f`(h՗NZjB$92~ u.Oeơm)t_Nےtj緿Bp`wr[#`4J*/WcIyyh[S2&kZʜTP41_)Hp:˧w}&5Ocv'8}'Ԛ*mV[(g|jZK{/ Z6I E*34X'|`PBK4Mm"uS/Xx|݇SegOJ,%3_&osu4\NNU5qol6?6D, >Pxt1~{a}O7MiW㴃$ d1AIF8v.ޮRkzCgpm+G$'W=Rx",!n mpϫ/t*̢]}x o o!/˚*-\.~zo?flQ% 2G98P8ˑ99^LA w~~j]22'ٿ%nUHdYel(їc>@*lPW9:WDRgd':`pÛL\dtn-49sЖ,S??%gsGj[UmN\خ0o_*bvΙ,阏vXHlܛFTk)UD;|Nt[D5^ƂIa w4^>BCQFu|0>]GDN~n } Bu^99M=FgJ5s7r߱2La"DLᄇ]lMRW2[trîMn ?x,X/ʼvH06a ZBUTMI 8h6;~%.Z\oq|oƗ& C@V4nչ2`*d f4eK;䧟e5Mg&/ssBJCa]|tgSK;&2bS:@"@^/Ru2&S F?t:9-w 싌O6]Bu<.v 4Q4^;5^$2pvGv&&mEc(f0e0!rr[ty2: ;ybwl|M,dXA%z7\mА5RQ/AI;[ұ ϖmWOOU<pāA*%(|푍3X0o1-W:va7HA sٱV(BrVyl:;=X rq%* ҏzQxjJ]a"df6 _m#5Mn_\^;17G}lz8F} Zm yhбPOjwTnUdpAݾPm-3-.6ʍզ!uHO]Գh*ͶC sP+I{xrOaz,;89ȁ͟=01HqRm,ϐA%z5񄵓$\ĿhTJ[] )@q;lx6,mv:$ -a{Ucgϒ$x ק86vX+_iXiǬ'i &^<{_歋4 #x nk&=-ػn5锸 yZZmSW3ܚ-GS<7baD`Y3\L-+)TZhy 6׏%98s-{2qyggN/  `KW7}wUww̚u?1?ǂws-~y*dkSp0Lgkq|wWl F  }y"s:EJ:YeN'#!Qߚ:*blJSfh[D)+#Br9-)RQYY~xff)D/!υ zNѡhSW[*il^OAEU- 'IF\4]K ľCɅ&LGѰmnk(Mn'C qȜ,4Gd5cSʜbg3xuUh]q8lx\6☰ %"S"tɹ +2 m(nIDATxgD{ eYU$E')-/4ٞY7w;qq3fwvG3-[=Y,oT#tϽ()U0e 2 {66[66mMhcFlش[66mMhcFlشGj-KNY5)V-TBT4%0{u8! )#Id^a_!wwۏ~% ١h%WIf59lt^<b>aȸ$EpHIŗ5ŗ!$ 0,nn *IjtEq9 la[MD3*3 ɌF+&uv9h,$*EQȨ:S Eg@N[f@ wfUnϕ)u6}tx3jV$T§Wr:O(jD6,΃"qtG^_%fJ|t)_q;DTY̕D|1Wd2c l2E >ېTJHQgq p6Ssx<o c9/Ygu'j,~V^;Y0gOx9;F%8u3gײnt(\[T)Uq;dvƼtxLtnfTr"w+eE6!I NM8=ȡ-au21 N-T$,[#A-&_6Rۻ͔HfJ'\8?Z`|^~~ tIbLQCqzbvi.-s0FU7(/o?g2hro=?Z%4_ԋ[BZ[* 4Ya͋:tM/Ω4/ǩȔ+]a*UT5񸕯)GSÜ]P5 LkK:Ut;l-XD$p+ Sdj kN)r+%n3u\ϣ~ e:Qd@0yG$".u:Lx5y7\[A_:94HPûRlqlw kj '#Ýuɗ5H"KPvɗ4^?A_E~?Cbks# _l7ki5$q.]fP#k*maPDϖ*:.CdlƓ]2̲:{_LAEp۳&7#=ʪ?ݚ)>HO{8nc>ܔjyutݗŸQVoӚKɎ8'iLkz̫&o}6$9ط5񕈖KE3p'E)UM %Ḋ)S_I-oRo$E\ϞZՅVg~~׷Y5,ʆn %eƖLTxg~|±ݱv.V}h3{zZ?DˉY^/jr-l[|Pb.Sƴ"S+&.Fȶ+rT4/-bUO'IfMх cR8s}7GwD_pe[dǀxU0c*F $3Ov ?W+1%sĪ_hY?$WxrGw۝jK3߻8VO?iL*d<$"B7w-@ðxx%V,_8scNI|#2c>qzse yq_}gro>d-%a!q&UBO&p+@$%i>iqw&da njTdd 6u{y@moSp;@_ Mk!ٴJQhbŮ+RBߟP޵m4D-\N\QվewT~s6O6GW|G$ΤT$DW^Ι4U >Atpk:s#eo7v{ IvpO/(}|Fs櫕fRT 4ލK$OuQK&]XhpÊɛ9UxrGWۭK!Um1c&WmZBl_v{5S<[A,ظKᐨ+pp*ps|Ŋxg3U~}z'w]ŽunlY=[Fә",^oX`&]ip B|:NmrW2Ubh] xk[:$Ehp+@u"PwY r-7jXxW|OD۞'۳i2}k5!sjî76pF[mGxnd[m$s!]ldU-_Ɍ|̦+\/m m`: Ol_G'ć3˾bAʶڬ8 ,ԙٸ1yF x^ YմoN+`` :ɶ[./ep:%U/[ H]aTn!3i$ )( l1^>K4ۧۇs H*=Qnmh|,I,pH0aBd0ZC+K[~D,-`հN[2EU$>̱Q:=hV4 w |v5KbA3LBAg*]L*c>F|vǦe3/$>M_ـٚee=kEfrT4 !)/rɜF<1:j7TS7r\/+gOc,8x&OgK5_^.-bt|٥hRd UAb0);ѡC%_Ni{,!q2116?'eZOصc]V-9-B+tc9*UɗT^gW2dzӿ8u#'f7({նO]1mm\OIcw9jPîA7MΦ Y`*,LKpzgwGr8%Ė^NWdJ&ŝWH̵IbMJ{֞})\CM[|z佭t>O 6\fJTtaA:=c[i.m(FsU޻>bTZeSkh}^+Kd U:uCߞ]y0WeFU^?gӃ{6UYfo}ח14tS T>߫|yǁ@oZ\[T0y/VU$gpj^̂Rbrw`CxzͽT4 %Q(;)Vg+ls'phxa߆ 0HuzͩB"aJ[ľ'7t5 Z!@`ތϯ~F%Ӷ+=W)ң2ETBU2C=۸jQʚǮ-Q/F >jp}wWNL@ژцXA/p gQ -aͰ&>vS6,$+:C8e^'gLUxL}awKBp .xj "{W{(A*=ʺU,T*\MPAE3HU8?Zo?!)q85\_# ϵܙS"yu\/^#}p~}&B +e+X,&S6t.nF l~GOW_\X?vʼy$Aԯp}=qeqY 2: uküeJM D2m5 Kx`vpkѢ׶W)UK˴p/KgC;#|p)Ӳ,u|t9JWun=ڎF>w˒tܞ.-kRΕ=~,Ko[jᓫY.^FuݤڷW'Wu` ]s] {|z%\ 7J\[;9j,R$zX̔ՔuVeaȦ89"ƯNsw.`dV ƊY͢^Kf("Qp2 >3̝2;fYoΖIث_t0(fyh Ƶ=[Sihsx3/Nz}l*H+&sϦ l 3>ǴD3nL ׷; U[+@!`|NX E6t,ɳ"^^}P!,gnxi LimBpzTs#Qvzr˕ nϖ8VDZݿ6's%*ş=۽3i .r]:;K+E?VxvW.Iiw'7 !tTKYB3`cKFFq8$"vtbnmE$S1iD)s90S28>y{%2٢FgE@,3U~g:U➥;h˸x{ÿ|ֽtA ٱD_ΣP֘JY,S(븝!'#Cn.&A:sc@bp1b F\3"tU [5NkK5"{%L {bK|@tQܫ_ri6Ǽļ|F\MV xzW2Ek%>[tpG,TL K=4z;N x$Qs6t|-gW-v WnZܚ0*22жY3 y./õ] ٤hV]Ql ԽZBpe y8}5]Pe^Ә5XԿ/_/w+,f ~3$YWؿ9-,I 1y!Sq9Y-`U|} XL뿧u?幬Ǝ!LKpb=UVv`*8bdp8K^ۘ]; CE3< 9(iK{Ig6I?ΕuY\&V&ǯu ˽M7p^7;fi ޛ̱u0}wFػ1Ɇ%hf" j%TV'Z5,N\mpOD㝱LMuCO$DNi]!iQ4UA5{#2BQ2[%49dxnw!~pl0[xG:1Lf$saws- Di3yv 9mT?-̎M0Q|w,'W+NđN6q 29꺛Nނ.+wH+b6 ;9nDQélk]!UDj}2EtM{(&|}"S4V}Y(-Vx y`hmԍ\C[Q/6ݹex"{;,rsxF$#LQ5Q2[7iq?:K2?:"[Q$UQ %=T8q=G6WeMJe,N(Wk76Tv?,ZjX*}n6x9xo,ktG5Uk4$L/]gn eZ52:\ szh&"5thnĢ`N7q &<ģ>&4G$2fKYK9~L*:< |2)/ V['k֬Rٴ#`Ĵضƭж0wt8M!`s%G;}%8PdY䵒k\) utDYQ)PVyxhĖ xy$3;#2K:`TT'=Q7vu&6x[ʿHxd<èY)Vuwg= ,7 'G$W:ڢtVߴÍ uF7| _-,Yxke Ut&ʭ Mǰ㜹e^D@ghh2j"iW z6̵ PXrtSp)p'>`&'S픹2^+qhw.?H:%վX>a@D IcW'KD.fZ^2Dq/ 0꟢3)slwe- dat\ 2cIw <>OYee9j$r`YZ=S E3n dyʯNX//Nx_kHvPƧ7SU%@̤KEeZEU_kp}4b"̗ yL[wl$(Qe Q,+t\ې8塪dJs`7LQ' W9/rwq[ĩtz'6 L=o\͋!0S0Ð%I*#aͯNؿ)ȑ%iX% UVD+{fz\aù\;D\,Q6X1Q5G :-Ȭpz4cSDM$HgIXB߆a KqpijxnP;;kgE)U~f2:R0,pk*K`?O4ŊT…I1aNEY.Eeou9eTP#׭Pj go$q*tG=1O[![4Ц|؅Nk14nGl/^0u %2,eIMb^#~%5ݙ<̱]K+f+IBbKMnNPp|ٳĝ2 +?czlÝE<Кw+QGRM;39^^yaOO~9}+ƾw .Ev_LQ]n˓iuk ٚCH%CSGh]9W(W{[(3!\`MkaDʭ2i2`"`o(LecwNlJBG!X.v]Kݚ$3%7${-ZfXwn;.'wY(V;~pi\³]+R) H}`wE\zMZ鏻tS7rM˓)b=o3x2& lx7' x@ _p}n] P:N\q{ >OfW]S2gGs+b%"ɀڶ~ k*$"`W-^]!C8vi.7**|t9j>zDl'bo}dlğ-mVYě| %ҽ.J_TM<A<*_Yo043:_գe]nJ$p%vTer^S%Lpt{ E8[ev|wN1S}:[%9xlDrҵJ蒨3efs͉m+~|!?ޙ˄i7Ănl2{lVwE>U@XDGIP%^ZѣL <1G͗i|r%D'<ĢoJ CO}p``O! [Xk:躌%e |}2LE&2F\,(Y:l xX+IqcLA5ػEgoel#)/Kz Ǝ K/)NΫ}2ڽo ݱǖ$@IN7LK*;tGtD+l՘JZ\8ySV >L8dcFwܬ)ersǵ|7 jR/8acC0+i,ο[ R5u}O4.f\zʸO? a`[^ kv^b놥g,yWЍ::$:k@Qw~Z,s檃?}⻏=3 F4 &=m[t3X{d.[:׷E/Oе?S=$.^F˳˚v[QO"f]2UԪIGd.,SPKo@ťE;=q\[5#ptmh"wɕc0]`fZʨc-ύD9vګKNn-Xli]^/sF6upegWƹK-Ŝ+',(fn6j(}߿)ȯ,H w, w \/rd{SܞQ9{'`́/)񴭯Ȑ[w>'-8" AX%xxh|[Y^cSwܞ)EN,auK$/>4a1ط>Mkv߂IyM? i|h9|jDb%w莺/S.}{& ,PUрTL 1Ws 6/e{0LPctCC.Jߦ\p;>c,IV[`NϘjѠ! xl26οNgr՞af ia?Ufkа'|xk<ַLNA觘/x\S6E3piMcI2O8l]Ltw\+=d{Z,нC>jXy^Q>!7Ɲz{n3:`HE"3xi_GӾi슸qg2f\[b;{cXXx܂a_La՘ȼT,!Q}VOWyjz~O"UMs nt3,z6TEqMoE X{ ?+ UrsbT UFA5zץv-2i?\lLoosz3e+xS;" |Mw?~q" Rp:eS%~CCi 9"?y1Wxr1)GǒJbdW2‚SW,d%x%%+{&at"r>Fo}1%gwIh;@A9;ۊ[(^KcE>AlE^5S);:qUd./mNo2jſ/}ĭ '78:{a ^,茧+\+"DپȔLQY&e^[[__e- dJI^9Rv6tFf&`!$_0uRVu^2^ssձy_LLڵ^8ow\dCz g l~:KZ-uga>4_ Aߦ2>"_l,޹xۇ-k:BN~|NѭgLdlheYG|pF0[ިhpk˲juyHx9ߎ <@q[HڒtH] ތ5a{!IvG 7%I E}Y-r@Q{+Lf2;@>=Ꜻ6tO,x{G;sitk{żņTpPߵV̨iQU,]b=%2Mz n]<|<?}:Q;Y}/:]wt}mۍa4s)2*H.~yG'G<7]Q7?, [P6V-EvI/Fx N_zn|!@ͽ~ E8~эX9Z8ihMT^'Z}K%vɞ[cj+M?5D{e,lOo^+F`Yy!kc4 !I|2念#--\V[8>/ymarn4 &KD >e8p"xya_{-c X7|I6E0CՕ߼勜ᏞLƖc׊e IA]e$V0W Yz{BϓtԪAЫs;P5B`0hLйΆ>fnŠ i ~~U%@37󜹓#.<DE( ]/z5_ ȅ{6 sks'VqH7qpktOeJe;( L4P_Yԯ /#{N|b[>Oq`3p(F>XJiqY̆fu/]- V&o}>O8hw{649S3!ٮ?$*s62U }*1_7ą%'r$A`F;LsO\vF?x/Eb;Eȯt}+Epa?ݬp,}Pͤx<{;E==z_{C["SlCZ38}ɻg5ՁyL5`Pϳ* U)YWna7;V` $Sa I]ER7gL/jxއ^k>~BQx% |ΰ9q3VRxpV"kJpoK u\, ^u35`C]|/茺yM'u?:ْ_~7v"K p<;\3E=!ׯdo9Ȋl{z},ž}tMXAW%#*Ã2w&ƹ"XXpNGDIusüS6)"oS૞NxF_Y}26Orޟ!wÑ|vj?}/-2`U>=n{ kZ]Ω4]q[5Օѽ ?wٿ)`6Sۇdz; ?-SH@̭م#C.q)۫u!@w6[3T F hO z99yɁn^AWx}ք]T‡{JDe{El"j2c#Q6vMf{gtNU$ξo(\ Us{ sෘJWjtvRB&rýv#ob $UN(0,{NMs16p`m⡵>Hl>RX \.صIl@ 7W E{73XwVzX{qwflp$۳@&_p36n6o`?µ-%%NZT`$_bB&_0>+ssd a`C?m[D3,nO52.3-# j(H<]IT5 (1l0r{NetZET6t;鴈 @BHll& ./ý6w{yVEՂ-&b S**JGȢ;. AgrHp RP+EL^"1YKtG= v{艹eb%T^'2IT4_ ;>)p)E!Y IwϘBH $2KnhDUP5PU\AX0T%B>'ΰDIзRDW4WIl+:Eդ\U*(k&% !0{N%dEB.EB%<.^ϣu|2a_!Sl MMX66mMhcFlش[66mMhcFlش[66m]~J%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--5dia2xrljuq.png000066400000000000000000000515071524103652300222310ustar00rootroot00000000000000PNG  IHDRj cHRMz&u0`:pQ<bKGDtIME uR'IDATxscispAA&I2)U]U=3ӽ1;;kBJFw3btvbgg43;v{Lw2 3̤ @fd& G~ODI |p{'Ye!En@=BB-mj@ hsP A#Z !@6G@ 9V/@ppY.K2X t7V/M h+$B.hWՍ~H2ƅwzA R/4&URy4[Oز,m~K⳻I8fG.UF$T(H:!Ԃ1ִͭL3mGO m1!2,*j6 IPeP,eƩJȒ"Tov*mm``YO1MRq:# Ztyx PUbIt ܰbYPIg+xp;;:`8dpp~Q샆R=]/0dpt2ga"K2iqH,6Mc5wf/oOƈ<[0-Lzw47^ima=[k{6,tâ:~mk)"EUQg ($* قC"㐥Qo~ Y/l*ޡU~>-Q ZF{)>aY INUA Ne"A׶"mNB  cm\is7gyu:@wv.h|:L7LRf9=hk!ԂSs@`pG1 ôz9sK1F;,LxnM-N%h 覉iY}v1-tD?9X,SAZ߃mL;p vFnrg&Ri|>l.a%e~ꆝ0jj]W?`ncH-&LF5'a&flocR7?jk+"j9[3zJ?cP.sV^`ؘrVHLP ads#kT L^i?7c!#aB~W'8`l<`.<,*Hg[)+Z:Lf:[GFC& @ :ph7~'e8elg}BLltody.7DbRn?I+Vwy;V/Ol& vV=q(Lh>AMσaDZWAQC=wP2I4!*rw.ϥ`K$Z%7)}U:bl(DLTj9CQ?T[3!Ԃ\{T}F8h?#JLouBu*_'4"e~5ϝgy!ԂR,ndb*I,Z 1뷅z6LJ[6I&_K/٭q!!.Bd0R`4֚ԟaXܚd]^C=s IxӜjA1L[39>$Whb!& y\߸`N&ПM-u; q(G -lIQ5,91oPcLI].cCBWa($wfsB{e<Jq98:d?,Z x%jBxHh4wn}DM? Yh #}~;vIfKܟqXs;Pj${T 9<%Z z}$%nP ^ >d%mf-4?w'XLYV"CyP;IS}/ eg`ްD;Os|dw[u1\[)!!s#ATh m |[,%ڡȌ Z h UItVK 40Cu3\IBV=>fܙ >̭vAC"!^?Ys& n3V|z'JEr6^ |HAxr!mZ/'xF}!c",d ousKTL*[F%Z}$tf-R/Ul4ETѫzj.t.>Zvj/xb?:οO/_U1K71tO& Ո`TTt$"SPVtRʶ9v;n] %Bik1% rˁe ->-UtV e'p`GױB=ZϿGo 2څe7p4~ǞkdeQ6zegS(ۂnZN}ˁRnہ@y2[A/jxu_G Z}aZ neN=#I$QV:ŲAW\ϝW7,*n>ߣ8{;-kL0;6+x3ftP2I͹ةn+KUWíU&!{FeQ,KNS(iKRFH up|N.Zp˂$UA0-K4%pcdY{fG/*oMĴQD< t)=$ 0)t E|Y'_4]R47Y.;.bZL*|vslhӐ۩(lz,ÇB;ZRKU4'DO$%y*2Asr [-j{A$seG.O3 f)) P$ ӲPd \2Գ汎_\[b,ؖGbyŲۋ%^gA{aכ{ >/tŲN*Wfv1K<]2Kl iY|soBI;03KE4Ԉ.}:[xy*G$$.ND{ v5iץ粒O/[X̭opD)Oދ>O NphXXJoF,^@ċS} xM7{\AH l-ULϥ[!"P?oZ鱡ȗneǫ.òP;O8?eՎ3ՒQ'Pba/[MA%8ڀŅ["S x9u[Ηlj -p>]gv;`Y`8?S }vv7nvT8 4wg$]WS˔4X?x! xm%Ԧi_.p;.-4чL;ɒS=<ëx>/ ._^œz%I0)t7d-S"W{vgYpe:N&_!Qv+JZKjtQû-Asˡ/5L_WqYw#-K/X19yȥ/K<]LݴUm vyZS,SUgv)ûOOܝI(*>Ƶ~1,$Dt4Rވ,K>a0ƆeIDgiC VE'Y9RGZ֝_"Kvٮ!ŵ_]\ +F,y19UJuv)ˣ{ 5VB>t He\/iHK s}$!KԻEzu}hNDH N0ۃr-5Rgz/[ub hȃ׭R(i,|k[?<fl;B=R/ZĀx!ݙeu;0%p13SU."q~ c!QxgWQϨNn;<=CDӍ=TȵT.Uw$57WrUx("!bvR:W2eqf$PSR^h+vt!Q+Εq֪ugzꛭý~{_vS n`!1u>vʱS896F'_z_$իJ^j!JE[n":w:wv;m2~]4lĥ*sd0$=KڎojhWwt?~#ҴuL3E?df y0Ӫ=ky?\EMTEȦ)WBB⋾w iW77iع+wMyY7(buS\6WI .UFLbv9nJB!~J1Ͻt_\٥,XEZ }%r"sd mǣ4S3I{(]{7 )Wp(2C{FlA YI-^tJs=R16\nbj5x5Pwr*2 Zv/0ڻÝTv[3zt&;r8TQ9Ӑ3'K顨O8lNḒkX/16UdM+j$nRʕ eAnΦ}b<]{XuTOQdS#\mH5<`WHAs2 'mHl}% HOv_)B=R/Y`P3iq_Y.>'om5,fxc/ˁ0-D"Sr~O"/^˺.]"ᇭ^sywfZ7&zH\H_ 4]uduXl"ExDI%4}킽8KߩXۉ4P_rV]yR .¥}=Ӓ:ڹx0 x;*h(by.aMs,>/~Y(̓K{&ԏ=LH@%f\s*a y`KwgG[]%xSݓ} l7$h _|/ȏɳoW\˭^sP/%e,ˮ>6jjlO3!K'Ftw g;Kd \{mGnwN*`Ս'~co #o͞s$?w0n< )sÓn {leYL?K1=²Ux=,p_hCNޜqC̑=j+"45NcaY]e'YX- e,ѫ|Z֓,x@:W$+ý~i%`qg;'x/_ff1Pwd Lq b Q|5oV/Ύë3ωt wk||mDSUxk2hEڴ,e,eѽ`k#^N&]ζzIrrJ7ảܦ'!ywQ=Hװ2ʁM7d^pxOMV[OX\+6oYDw}R|!y=l:bY'U8޻堥cAVE?Ή 6HxYȕ[gȖ"գk r}}+hI8s 措/ɿytPd.K_^B3\/|}oӲah Cf5`!J!a_C81jwه"ʕ<2HpNUȒD4V=Nǎs©*fAPj-nͽe*A8kݏHu/ZU$PKCd}x!g75.;p[ln#ErQw8t'ct+Wn/UdnoOLs; QDgU߼v;tHhI~K~f2E||pn$|젽+^}$9 y0-֩(,|N.CQ$ |%,PdޚCP{~eσ% ba%ҹrǻT,% \JE3p(2'G꾲WwnR(鸝 neqs|{sz|xcV]v* zYm O2H\ҵG YhRB_M}*[.8چSvN+p82!y(Ipn,ʡwaE#?fdVE$8}8B,w]@TK߮/l$iҙ-TB~dNswVH;U%Pz Jh%قV[jH`I<\SmN*1 d <.Ȯ6:#rO֘6:cCAh(h_M-&ѰS8~Jo؋e_+T\N0;#Q ̍GELJ9`T$wg^58yCL+ryv:-J~ \ nn>Α+6ql׭u||mdE8u8›v`}@ù4zI1;'&.[7Ȗq &c 5t1Lo57eg]=.Q |N?3רwqhO3x(: Ixc.7;KOsd/&+>P֚!6ȐnPreΥIJHDo˱ iq hEEUfŅө('b|~kLWS|T<[\Xsrh&}N g4]Q{r ]EyeBIr_^D߁0|U~ޚ9It">n|w0sC-8ZޜzBx\2i-4?7-hziYϝegX aOIĺ5C%ZhYqsAB2[jZ'/iɣ5ΧY˖ۋFwqdC!ﲜl1R\o˫s|rsSɒhmUor*ǒ=R?lGEibY)#vuYxdO ]\68~?Q(|y{|Iv>:v72E%=״c04 |tB6_y}!o4ےro<4-~~yML?4#}iUc-S"HtSE>StVS]oBS}t?WzX\BfiKuR.N7T1Hd bTlP,I<B~W%pp>Ó ]!eCz-s;pO3kcP?X}BsM}vBbpaꄱzeV#t/,ʕ^~A!M!KIrȏxMcT~c;t)[Hʤrj~y(٭*|.B>'~sS8Ӳvjt!I`scѶ+ue@}n/3 x$IHgB3 Lrpxc0|gddwÝ;N#84)W:o]#ݱ焺%6D;>->km/% ̭(Vt.zD۴iU.gqn䰏K!\=j/-v}\qrE I8>p׶ae""dh=D(xsSB-eI2\teÓ[U]|*s(y?cY_^b-C${vWyBǟ/1P̑HC\0x^rsq<۹9Uô2+",Dm#:eQZMYb"!ctA xty}N>']^GNJv L?KnZ-0uϾ߿Sb*' 9?ֺWa~5͇h9wL8kydIx/쎊nɗI5;-T0Lhq,|!Џѻ"}NN|nl/~JynY?kQ}&u =>~W$%H_S#mgo'dI(HU/0IJhق]%p-VwWB’ݥy4s&{[t:ôiEHdty^?cv(*ty;g)̥]ʲ)^Q~$IXE]rAݴFP BL-hvKKD9}]8dkWy̑}'֦eoqל;rHE7%C څa1n5]DG"vܲ{..U&wd"~I?;tl§7@{7^?,qu:R]7p<ڱ/F ,J]a ʕvX؝2 z-g~!" jTN'-  z 3}o?Y#)N/aLJ,I\jӲXjWt$[rfv:]{jߣv).6Wix+,% H\onC?\t nSUxD f,I\ ^d-f9kBI']M[Ʌ.:"뒃>;PetfC>Bup6Fk-0mG\'SŝEwqrcF {t .Di"f.639+o*9AY0( $iJ3mߙ 5V~KnhFL&xBD(>~).7%%;'LTfu wu{ќ]>箻:Xա`T 6ˁHpͧ 6!BtD*kYTL4')ĩ"]n<ʕG.6#w|y{tGW):,ے`CxsMS3^|9$;)% uk;#iI8w@+O7oaInkY˳FKw`ēRٱ/QlwOEJQ\ ć{U,vҰ#lAߣV׻ >=k,fXN%^|Ӵ\8३ҘHƧ&awfs$;hn\de.|fxLskSӂSK1enXWtx8b9Yȼ1V[0Dhހ!;/ڇ/P 妢|=̵-s[%po١cYeJ{ȁ ˲xPSӘ $.^c|~|Gٖ5 8U;,eDHNbp et9GU81רBu wzT?n\A㳛 <"/ rt0*ܜrQx5˲vzf99qX Zo4ܵ_KEX1(ipHr |jOXN0j{C8fP6g6SI%Tm2{YX˓/ix]2gF?1![+bv^Ma">Ju@hzxX_L S5тrІow4 ތ᨟9h.qڦ. ^Q(\06?",b9Y R%k͞IÅ:v&Gb/d";^,BE7 83_ƃ9 .5%Eǎ%#\:ч[UH||}@o4 íGkre\N {XmXMHdJssjP(DY3(=N!Aba/iq_A߹31E˜}sGx]{.Բ, "3j.2G%<]g-SjLqbnH+ēEd <ƫ$\j/82uR,|q{ ,(xEt{I,PKj{LkG[ܩu(&B_."sd.KD9`'zFq98<=b¶z /9BԯEEͪ`2Ws^xJYxkW's), Ƈ}D7Ih;DU$4.x =A7nre:ε-mM ]^RS,o0mh$Ԓ!x\9ϩ$I;]'!V/`̫&=>FZW^IP, > &+su:N!ILJ׽ 4>>Tu8ۑḑ7Pdw?irƦ N,4'd `n"A50xg+AO(W{;1ٲWQd0۞eeWS,' ;O.w4 ML F n\D*Wۋ|=L(*C9?=i5],[F-){_Lr$[鱑_P6|*ŵGL$$Fq Q(\}'Qu= ppD4TZM,I 21^ڙ+q9Noud[ uLAIڧ"qC!keϚzj7=*{ F`YΗYN_Q$9'R;P+sXX>Pwjw:Bk,$vT8 "+s .6˂dZxn=A}=^Ϧ(kwR ,ݓ}~*ÍG.e9>׭r`5cG~HKۗhkuh(n~ze b5Uda-ZmC!2 {GBI{XvmZѰǣr+{i/~8P3iP0M3y>$_#pͩaqsznTsc=btxrZ9xAoC_KoسjD*WF$"AHC"w$xf?y%:VkT43|q/IE@ljn1K:WWHV]Ϗ tqb l*rB Ǩ.N&"r{RO0L (=wcjbetQ}^TQV}Rhg{$ڣ,IRh>d W]Ϗ tqr#kketKIRYuu{u{ yDy\3ƣUB>'rgWBk*&'f:aڧCQ?4u0LD<pqx#rak_,s aKe/Α/iBG;w@ uZCbp(pAn:dN0Ԇ*ri72c>tK~vҹ)5DKzc)W =|EfyBYgirjɯ(?|tmL‡g\z9@ u#A<-Zs.2nƚ"2E,a0i,% |=Km\jg) YKzwݢ%}H|{?N<lj5iset=>1dEݭ^ήB%qɝD'^<{$M[-P;קu{xE>f5]ۋ80^WB@7<7&"sX=f2LDrn@)oqVhC,⥿+_Y"* ?:4~)%1:W]dN/FMŮC$)}UrմֲW>@CLkwȴKG{x<įn%,rxCA Q:mQX$2%LBy. HiJz7,4eqϻDDDqۡH9H쯰t0ECg?#?x|f7VMkP۳BDKvn~/C>/sg2,MLׯ+̰L=x?ܱ1Pݷ ~#}gP7В^ Vp#NIn"ӟ~g{afݻ}_Nbv(QyKqo6I,_z!Mbor01cP)3erN+Ipl08~k;L Ԣ&TGo 0q1c|K ?ݰխW.2aQ`Vݧ;?viNB":%};mE7|L { s_}\1q(2gF`o(4n$' HeY f!-ZҟTn䰏_[6g:M^9+|zkӴKI@_ſHw60-nvb.9n2 x9T i^_^#W`r(Nxw2e6 !mDl4W[L }Kf,XLXI0 A/DmyskeRyY sl0e ^Ӳ0 ݴLD+(U#?V/anCRyn%pt(2Gz^3L2i:_ڵWJM]~C^wwn$ZL5ѐǣUtj +`Yaai LEE7mq5m]giMZLz{ο{$IVD Cu( W0~(̡s)R at\Ž/_35^, 16%չg5*SUV+ULB%bru[msfXaji_WC iڟuie=g,CPB`;r2oZB^lIw:t|@:x{xm}nNռH4UJ[F%.ߠZDYGM7loj#0Vd UEPEfeJwUEopطw(2Y¡gEBQϯH8 TGBO_f!C0Ms|r'A[fudE=L 8PL2emh1ѻ=f]8 ӎ<+F~:ݴ#VMaoVM8eC$ٹcAΌZD`[DG f% z3!1h+/;'W uj@ hsDC !@6G@ 9BB-mj@ hsP A#Z ڜR*+l%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--5jgo8mhcjsw.png000066400000000000000000000337431524103652300222310ustar00rootroot00000000000000PNG  IHDRF#S cHRMz&u0`:pQ<bKGDtIME u6IDATxwe}97|'ݝ E" "!;v{΃%Q ;un[,gAv:6l6]nddIB T@ 4Dtj ZSZW45td$/!'w&+& 7R %ӎoEMnqdtD{?*[ՆJRi*T* 7n.[[4`%d#o-*n ˆiie$Y7p&nb&T6N< r :9~=!Z6Pe>ݤ$#!7JMRE1O9:zKrkk rMB^DC$&[GLuLa?M3C^Mf&[VQcnzE$w: ܎O455*͠Pɕ$Lxp9zs@{\ӸT*ÉAxME']Qrb2h `> K&Q/1m=0)T[e|6Npt̏ٛr./1$H$^!6/W*blNd 䮩~=4YYH7yRTAa$c, puY4Z*+ $wL- ݥrks; q_֭0M+ fF1#]_39"ƣNi2^r;|Hc)M38=W"C|Й&j\[*}5FBW|/GİaUu.1qdU:ϼc9p|:F"t,hWs >v" $lJ?rrh"}&d\],phGOFXRƩ4\[.= %~qf+21hy?/C\96~侤81TKW9>c8tFR|O1R󍗳 *TZff']DM>e5plb& 5>kRutñXW6i\sY.>qWk\`^\%:խP5ssZʏpH_4ݮPQzJ]`9{==3>t,~ܥ"goT81qR7L.H؃ F/04'^LSmu8ٝ^_/3\$?nsmS88ar(tLڵ ag詢-MK3 5{xL뜛N访MlSRx\N!irW's {}Go  US|nlVU*LyXԂ6TXUuS689CǢnNxz_-qߎKR*dPd &O|?dq:MfpZly"آBEϮ3:bz$t=|.\cl;X-V$. ͍:OC }߿nd5>ίN` Ju|{0b682"hsyGp:souU-  ]n{Nեj?2_r-kϦ8l2J:ݜtfuߢ)MIWk|=#QikXxf7Ϧy{T4^8#]Xϧsԑʁ"x  UCN7g_UqO`wWֲM4 $w,*.ڽWuME'Sh.)TZA8%wt8ddYF7s4u]7h4UʕzI)wܥ"VlF?^S/1N&ry񄓏])4;1ۛ>jK*+ -`8$`;0 $@ -\J\c eb0@,7&@ο''Z4i>9ҷ+4\"_>prx"{f/as1:QX3#̭9}%^4fl07NeDb!LMzzioKAJ]ٳk^L j2Lpy84ʕ" X IwJ¥"Ο(*\^qdB j7]d'_ZKy6P[,hlYjwT*'fz΋78t`Ͽ/͔9<5Bsr mMD'_Ͷ9D|,"8v~0#sqtT*.#$q|*3[?ZCm#7*\Z(pQWeK݀8_'6rfce_ ˹PEo!/XLՉD@ڍAJK<ӄTa J/ Ă=[g' skeKJF\[*@_ٲ!rV7] ׻fYXJ$:ȔtJYRjXDnʄnsqnb`[rfqW'GbK,'Qv$Qm<蛷dIlv\ZɀM.͟cA@\dK*]nGIbkeBA/Y . xwqJeǿS[l Q<{w\c̓Snʎr[lPw=ZnִpP lΖw~tzGx_?/ @UM61VϴJ0V9nRn>?O_O?Ert#¥b׽P ճ5J竍ʲD-2O⥝Ov|Qoi:ϿޟZ!.VϮ*M_)vim꽹췞l*ktI;riST $a]_6UXk\=y+n2smywrZKq~ʎ~ǎ/trhf?ݓeє.@ Ӏ+˵- ddxE ɌOLuI+Ro4]͸8l6TK>r&Z?&P*h74i4U %C;:Ϣ:/^3a>{)SF볫fLrպKWK|XM!7_vK 7|G:ݤm+U[hk|h.gBM[lѻlNdht>nx+Cmz֪饥<g(p]?k\v#-L|Y_0q%FK x^~N7cWuT˪WJ|xo-Ͱd+J $otzT kV-tE2#nNOX̶$ M㔉$^;kWw'W74$!+7*h=5:v V3tàKTtKiwO lQ[&̕ݔ)C&2vD7LQ{ˬk&̌ua`sz|]tH"BaRi(. ѷ^mhtDz^4Yx+` -Egȃɭ&,mTPޑnblM߬xuALG<"ɥŭ_5#"'quZC%"~պݪP]ݿ=.;.wS74xǁ( /^Eȿw.@Ԥ}Nf'"9#Izq;%^SBUv7CޞmS2RWݝny >ie렩x<)I9qd ^($a&7Jk-w 0Q/:Q>KW cQy]P39НxM΂kA-~.Go~ uRb"[?r\l֕1oD%Ybf4> 8#׿qt;e>rOLvϾ٢pn O xȖ, L&.vhZp5s-TQ- +% Uy ="6JXȅ_e#qPUn/7e1Lnqpel$D[m`.H삵r&log2!#nk #n> D0~ҹ*VS1xwwi#t+7;*3#z;lq?빆Kd*dY踟LME) ~/">mHw;1JKXK~ZW:ޗec,f= 뙆zщloΩ+*"5UfF|}i6ٻNYM:H]Iu4 e N":n 2V/H2Mt;&+%uа$u$0td+ l`*D#3C^u(Q%v]KW)6$DѠrպaVbVFJsuS6e[Sr&1;ֿc2@Ԥ\Ǩ:enCG}W*j&2"Mb歉h@dw}3$[jP1Z>lߍ!C!n;ݔThT_>$A/_n2] ytH{0u J5ZC؄ꞙJ;jfCra'% WF~*&]>_fr(˹}L ~?{-=$]hw]]6q`mfDP jG1'e /$81B [ilj̈5ӄTQ!nJiTs0HܤPgi9>v"݂j2xM\W0v|i#ɩpEX:ݔ&s N,g&^ak2a{]A^ˊmQH5+- n|q:ZKKz*@@ڕ2pnv<~4-*)l's 5q*RME/!79lC޶ܓb%=2,N7W$R)c:ǭ ,+uZKаuA0tsT3ҘbetA*_}$㬤 fh+4yJgC w)K9>eM7Sz]vu˷Ҕ\%-긱R逥"sJ\],v)^S8{=çu|24ޜ9+En5{ZClOmca.\_eIdᾣl־+ulY܆$$XUY͈;j/]JqO'w0+WhkG \Hv)]K%2Vl p`(kl? K7Rln_](p.T]x]6>p YIin1ӲGBF-]hpm!ȀXz %MSA^.l+ZK7R|!>koNC2'̵ 8gd>yc$x%^9*P8s-Ï?4@,` k|.;Fls#"W_ 6=Nirq.GX"x_#Q~ iqM]Eu>s_/$^v9B?z_Qe<fqB'2q }(IPUֿ/oϥi"؂A/+K6(TD}wc3Y#lŇs{)VZxqOaS wpK#!f"ˏd2y*ۆ?@^{W8M[ttgOprT Yav5fh|Ãlu92?!l|qC$F)qwzh\E~&>I?wLp֤ɍuhO.v-Gpdö[s21(쬯^I|wY)|@f#_,}(xB,*Ϝ/{]m&Fл %*ol0;nop!;?|o{˦`r}/@x7cJxs~νGfp}R`P?‰Ğ|?0'Wnq ѹEYBL&_C ˋj&Gp`j-o2pn-[pWsqʷ_sp,p\V43Wd>$ ?Zpd{ng9UBC9>Ѹrsىrg8keReLJ䨪vԵ2߿Tt5w4w;4g-[`(*fY"WQxi;wLⰸpH*V^Ш:\)SRg6hH`UjMH6;Cq4[YBF݇DޛkeKG ۓXN"J/ID̎G{z-TZ%bmt[繾VtDw0ɵ"+7ΡQNux9G6_JUX`f,/. P&s&̌$anJO=2Hзw"HS1xNFejWldk|Ȫ|ASۦc8wE{zZ:P 7s*`wbE$ s;G'#m)Nari>K'm+Xl=r`4^[Ը4gfNFq;{whW2Wef8pi/7+ 9 cfH:OLo}*-./1Lɑ84 OEl{TyJ@gVE gnVxBxhx_ח8]Qq>V|ec}w\X)qr*G"8zFQ/lvPBPSoiE@@Wnp;$ope#=ӹ]Yԕ0`'̥u/d06 /\,k1 0=scFc> .Qo*=&ϗyJhPUopxxX,t WJ,$$o4M҅K RS~8·_$#^ud9\SVf=Wcl0D4fRZTk ~x{חJ5Er&;DwP`z, F}$$t|trU蘏S~Q<j*k\X 026X`;99ȨOZ [2q`(߻7ީTS8s- ܦFBlY76ZqtquORo\YqvBzC ɰG͠PnRkԛSCnH\_siJ xn/U7Hd56 qh؃,wϋM"RBBE =oVFKPU E%WRL&=L z &&7lZ}v7ljclJ7L j]\W7UʵMx?N&D~armKnxKzkLl0MMzST)U--I/qm-LLLRU%w8n M~FM7P5jC\S5*uJ]e8! trM#UTUUelY!WQ1 lnp:*h8xA" p ;[td+++ JRi8`p.2yP T쟦I t;a?l.7n.(dJ 妊e#d6 vf&n&Sm4Ng'w0u1q5TEme\YMv&(NK18$C.A;5>&jl騺nm2Niipe/in*NK308ev ݆ӆ)0)T*uc&lMq$6Ncӥ[\I2qm=UE Їz'AaD  }H ЇD  }H ЇD  }H ЇD  }H Їvi]FR3 M۾[+¹sl<1SSS~A:lr9N>ŋ4O}Sh&jʓO>SO=kkk$ x/qȑN7u??OY1xyԩSwAcO?4?8~/˝ng4M# h4p\nJN??g~g:Ԏ@^~0 |+|k_~xgٟYR:H{x$141M/~:uZFX$J/~EQҗĥK:ԎrwwC$N? {'JOۿvIB,..|fۼ:L)9˗̛Wu/i_ľ q//yꩧ8~xuuٳgyG(2==ӧIR8q{`0ga_ZZ"0440H3tBX[[ctt4ddd=ßٟu͛|_6|1~'~__'Oix&uZHiqqqK G:(v  AAzA@AA@AA@AA@A,WA%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--7dzkrwuhlfn.png000066400000000000000000000401351524103652300223370ustar00rootroot00000000000000PNG  IHDR\\ cHRMz&u0`:pQ<bKGDtIME u?=IDATxw\\am Pz-@rȮ܍SfKvuwd-j%KP!PCL+nΔ/y1Uy^/B!DP+@!+)ZB!-!ACB!EK!DА%"hHB4h !RB m__y*Ш,s:@|6"?1 l.)k\Z+.瘉3y3!Zwmo_Oth OȰH?CBD;w6>9PČQ/wEh5s 3~}/JņtJ^C|Q/_z/&ǡE_gdJ4q&6YqBӁb'O&f„~m?2鴔kDvSS1NabVN'Zq8J !|EuRH;ߛߤ$m^<עjvƥ99_CΰHN^ȕ-SoMe~@EKR1-k/G*ڕ>BLq㘷T ]:%8g5 2Ok&}jꁍh Fͬ< govpnBAkۭOɨLFݵbz,+ SMCv|]ohpxOHԴhrӣ8QaLB5ݙ}h _yRTLkΡ+%O}1(ix̱%4;,ZLiK­A/V{@$YIh^.U 8457VdXQ!Ab}]ffY8t*k}q)Z8V(L{Z!nGt1}!Mzyx# 2I(D8?^@`kxz~ ڥK(Jن@)qO.'*}_7c@::{dēz^ꊷ8 TL9.U5!=\b61͜C|^oHB%GndB^R\ݿu{Ej3͜.1s BzQ=\%=\4Еqȡ_G: rS8tKNWm=wa_ozEZb< ]vnI!us=#c^S2(6MIǴf8H}%܆ǜx+ z5Z]NMDpK5Be|x-1щۥd6;%[qO{{EAI*nH"N'aXE(>[hZR$#-z x.ގ+-WTK3K ׃viiXLW:E +=65% Ds.甅JG H٩%LwMz-i+D?*Zk臺e؛Zp^`393matm(X0W=\f۝Ъt]jŃڡ FK&cտ%K|< t/3SCދqhh*fX $>ZW:¾q{Eىh^.V5+E0MdqPE @0+IM4܉sj1 J *jM ttٸy_zۚځy* IJ`>|Q\ O7R"=\/]]o.9} J JzSSAMB5*0ϯ,ZqQ&e%QrTz%N9N8A-Ƥ| Wn7.w4tWBԔ)$LtE %Dfj,csr&av8Rptg<3IWzyc>hd%1&2T7Y9ION: cSocPH]L((@^F"'"|wa_A#TƏbRf '+0 i/GXM <:&n/JW8鮬싊@gP:NZ0>^JWܭDO6E pMIʽ.P:´иg/Ex#cMMĠU2+MX^V:MMтCu3%?ӟĹspR}yějup~|&фu_~#,k֠X/ZרQxy7'Rn5SޡrykjHO5a.aV Z5[}uUܹy}oS/)M ˁ=%*ۃ}9"22oAW-ZŶ?ˌ;ٳgbŊx(>܁L1",?xZ7=]D&s\8]Fii,^t .%}DN{Q^^Nmm xp9s稫tof @so+K PS\taXvұ,(Jb%2o|ty&/\@3j8VRP?3<Ѿ;{q:eJ`4i|_`zG%K5`Ay{`ޒ5=Ǧ/ ~$hp%P|߿ 19_VIJG [*%KdΜ9\Bkˋ'p,MNh4# X-VǤihzWu'ʬuMMf*GϴiӘ6m$zQɕaPD_qa4֬YtA ڢd{Z#눮lgNNDi~sO0㈏3)MrUF'+Gñݤn*B??_Yϴ>Nf8 up, Ԗn>sRYtع!pUg$> }J @,`kkᝳ-m+G| R3ptM RgZ h*{/}͙C:BhE<&Ǭ4h@x_ y$iJy@TM ,\L.KMЛx!9>l9@w,hj_:S)E @ru͜HG\71EhQ"$HK4iK `oh1 ҟF#X:9WxН=ΰ5B ٢32H#j kp+/*nӪ^FF1itZqPihk1`=jmP X!]JIY@RIq`FD*GIO4rAR~26nDc2)ǯBhT*5S UBoC;wo1T\լtnG R 6OW:?NfV^ owpVqŠbSIP: sM8aEӉVxSzqDX-^ì< .RUgS:NX:oÕ㕎3HPWtՃN*;}%̜Al^iL-hi9f^?ـUzp&0G4bDEhxz~p CvL#G4siTX-#y(.Gzwp:qzR(b%X3¹J'ݱ71赤> 9F-([brȊ)ꏜ^}uDY<9:I[:d{>NX-1㈉2P| K;}q^Q8B!3"ylpEt/3|S!*^8ۢ0!3GMJG ]յ{ Ǣ1J ˟OZ3פ4{"ucu 뢥R1Է:8pM8AFm8f?'t VNKĨCzIքv̫VaLJT:ºhh5jfKNN]nt@T*(k΍6%Uo%.ZLTfqE 0+/W[V#Curqt;cqt >Ӫx:?N°_J8IRm1m]m}Uc7 |eP47-4Ʌax1łe, )ZkdDJT:NΎV[?x:\}?6ԕ˔PhH2Rby^ (gʱ߸}zЄ2·F, =\@{8ZFC_'GCdǒmd1moy0 ߛŤQќ4wqh ًqh}QU<Ѣt]H]8 X8!Dgjk5oaY}:~)ZANooU:N@pttbZsxc?f$!=\ۛї ~"IG14j3r-T٩\kT#*G=\6;}.{/D'nLiOighE WkzCuIif(GV R u. J0#yD<)Z}`2ꘑkaϙ&JrջUQD2j(Bŝ0zKGNhQ\IYIl?f3|85 CocunWwpC봑fQꇔb|^gmxp<t2V蔿pCP[q mmC^ǾObI`!+nw}o?Xft&&fF1qtLpijnzԍј"Th D %G= M4؎cjTȒ8~%zU_#}:T )Z>42%sWZqAWOm=-{vc_oTqJ5!#icb8~%8zo-/cئh"#2hX^Fzc s{Gk%%8f?'iqB bL1r&{菼Aj /IDz\`. ۩-يkó#D<55(כT=n#Hu|MU*嚩vXFǜ2V=AæH.L&K+%I(=S$Xt^H+8>,BD|)_o].CI]+X&Ek#6=&;wh:TmFF҇CJM0DN]WKs"{WVTJ/!2MzR$5p{c#;v☻ oL҇!밗ɬXNUm. eR0Y.s匌^|.F 7·?^^_>9Gs qT=f宵N%Bcܨx,iU7֢?VNEjbFnrݫ{nlwq{pGnusz@K@ѿUG xt=KsJ!Ek4t={xpi2q@v 5j5ƿ㮉sqMZl;Φ&҇ ,_ZC[M7`}$[q *rw8_ y,ñx\J Ekt89{ճ̤V_LyʠA?݆^.ofFn ?u>f*J'ElN7'*Y8!ѩ(WKa1;҇Di찳xǘPnz2ׄө۾' fRpJ=GEhU*R׮Fo@[~XC2%F@u$a`9g>ͭa4)Z~¹덤&X0!N8Zҋ6`{r1`v-euĐnT*V]g ӄ,)Z~r5ߟd"M.A]wG8BH&#YiJyNcQ!i-t$EWmh:>.5vnmP:LN9ߟ7" BqBNF ri)赁{x#G''1+A#CuB%3*6jLk$k[SqBJV B6np^ Ѧ:)z\SWN/owrv',h4[㶌5} u[qu~p%EG:{|ЋeBp 'J^_ZZʯ~+;il"G/`_!Pơ 7^:^[ڧ׿ڟymoin4hQy8Gfs)^Scjd'9ܜ?!cسgܸq /ЧmGdZ~.Fl)ťpr/O)}8x L/eorWDoON6_k?yYdLd;.Έ eaA5HNLÔ}ޮg\z7 ׿~\.\tK.m6ƎW0JE+x5n҇U:]2.#_vP_/r/k FJ>qcpSʈ̱lWd9O~o!m\Az@Z76&&O}Sl߾[nQ__h4~z4Ozyb6`ƍ}/XR ?]H7" w8svW׿;[{&h&۴4x0E> p]q:T*bIҕO`Rc_{),sg(}xA(لQb̤m׾5<ɓTVVR]]͚5k>qz ٳ3g{mT xb;"y<^6Y1=l`XsTpUZ1O;;Pk4Cokh# R:А>q~/GM/@LƕAM6<.q鶹8Yi)4T*FlXţJAӍL ^rN[KA͎00#)Zr.8ƇY/@u:7u MeH=2^Qp[N0hnSWfbvn? sHgtlv73jXIrA/-EVVtiB-h$֤0(%k~ U[qDxl>@\p@ ؗlQڮW)Fqa_*4q0GzE#fb_VTJbۉF^52x7*GZZwNwmqE^6ηՄIyDMx%˙Zi^,_qzki -=Tնi~ &CK}|.zK C;d0vf'j+9srK)]8m]vo6~n ZㄜOНثtk5=ʬ\ zbs,\éٺǣt!vEU++% 9*AV3hږZWO+Gƾout3˯3j۵G(C.D> 9*Ac4h^S:=nJ31KzN956k##ǕN3¦h=^NUZŴ2v(cbHݰɽePfwzxP݃^p]ky:oyZ/OsX-]o 9VϢIqJ +)$X~VTJ~x)>b%!Db )oDEGgm (Zo7+Lb,f(GΓץ+ju+Gʜ@q&dVsK)BlbU;:ѕ)_>V}//0kby8cٶ#d/ Chu89{U3I^@jI+܀k甎#k'BQzsS8vfW-͉z'&*XHc2åhjn*GCgңLDB,Tj詮T4EH-é:brfqőRݨ[J}`wzxJFb<ǒ"ZOR4>2Eddx>0Fҥx}[F˶V"+HxMb=55J(Z?~m꯱l\O%bpOұPWWǿLap97>}otauo\7\~8-Zu8͞`og/n_X-[p5vKc鹩ҋR//)S(k7ҹ/\:êUOau kIKp|vݪtŋ>[~3j bSWz|2?qұ$VG{ -.6l +M Pgg'_e˙3tpj9.YX1[l Vk^J4w*ͩ5 AWb?φ}8 3ME~`׿u.\H\\ֺjMhanSvc'dXQ9df #1|9t `sœגƍ$l6/~_|%hj߯l< _>3?)ϋ+0EFgqґ$9]NV3-;cc2%|$>>U xܮ$aTұ†. _:iq IFV.ϤwX ML JG뗠tzDsrh4|SR:a&]87gnңV,(+D}oþ]*_hl"B+f$)E uImK7O秠nRW@r;CtٛTaXY+<35x` /Z Tkh(Tj5F{qBʍ=¬q)d]场D)V[sY?+sEh@sqBBm7N52]*vPi>V-J+K&'2"b ǒZPM5)дu:)>ZĬde],b[T@oewր,ZNVe21CaBlU:NP;b%;-Dqct#ǏvJ4*FY"+ErLj@xy8R䍊Ñ7^6h uf*Me)GKQ (hD֐;B/CT#?)9B[r~O+gqJy(`N=l7%@"}j=h{ēN^V}3rKk,\)#+ ʻlod^w*Mߩ@{q{ƌ\ :m@"8/1PF`Op{כX7LbәL<];J (Mv<̌bQp_ǕNl궹8Yi剩IdJ Č׮PukqBScVN^,1(^\NˊfQh9\NT3=;#WD ^tb>a_ N(fzƤő L[cK;#OD귔!-ZU4ib RH_uK=+'N3$N\렪9R9'řJuCxGcȊ[u{h׋3<+"4mcs+Ar*gP\n/YII$CzD'㜻[ilhypz 1zN^8-]61]~PcMrKwZ&o).˷x<) ͉3|2t*e@vm1(;{QyR;>/Z7kiiFފjI+\ʳJ闓;#X"9'If>ӪR͝vo& K.]D6t M IEu7ǯ3CzDp~ g|_7۸py)ҋ%!! F\/V׽F;omffAzDPk/\mnIW3X1#azŎJlCS+D}kG뙘Dl_" }|A-z%&X"$fa:Tqc!+Y#K%oT, hۻ{ߠz&dD1=;Jc#ĀΝadV:.e&D2*EzD&`[mjԾ\b5b3hl1H#>oCH녒MZrF%'m4I/-; h]jF>BJňtxq#gqK/)1Jͤd+^h h]nF$!EՒ^T2mk/3rKE8To{}@ho~C'Q'bУ2Zݙ<u^71SzDRp[}e޼_gav S%B!) ˺uX盘+X"i8{*k~.5ai/rp.VT~zټ$*=?~瞿ڷk>-?}c=vfn\N'jniZHNTNF9k ʃ̾RC<#3UzR ȳZCr\\3xhp\CZѨt !^B4$"hHB4h !RB )ZB޽{ioo>~3HOO|/""tV^MNNi{a֭6 X,Y`V_dff /2/f̘1J"Ekn7Vٳg3e9|07~@nn1Y]]]XV>Mgg'ǎ?1ͬ[g>e%P"Eky'~|r>r-ZMMMl6, :zXV""">JVVIJJ&Z4IN~|˚5kouHLL#顽ٌFswy^>ꢫ 췙SR|(&&VqW^套^ٸqiQ^~e9/ȶ?яhll^?6w<$$$<ܶ_xHMM򗿤 x0ʕ+g?+'*:<͛<'?!;;/| o`0/|E=_z=EEE=|W{`2x3g҇#dINWW9׮]p\?|j.iiig?#&&={+`4Yv-< ƍK_*&nÙ3g|f„ |_&>>3g_H6nܨ!ϼ^/555~음G2yd~ӟb00a„s;ww˗/gʕDEEqZZZ[oٳy饗P7_d„ DGG+}HBAزe [ebNdz>c={o?inܸm\֯_… HNNf…>}῿;XVʸ8V^5DEEϣXd 555ڵKxwޥn<͛7yꩧ>v(կ>Ǐs.\bL>g}v?ߓs=>9{9*++>}҇'$I˗dsg_ s#G|X3sLiooȦGNII׋Jʕ+$%%}쀐˗/ǁ~gg'mmmtvvբhw||l0,R!))_O4 .]Nl^1hmmP2L|j>E4vsĉRD@NRRz݂Oi4Xtww|y<|o@?R|,55Ǐڊl&))`{Jl6~؝N^1qqqܽ{c_Czz:w>lB Hdd$QQQ>{% !Myy9z$FMuu5nz:ˡCHKK{xf6iooBkk;MF{{;ǏL> .PWW"`1d/_Zpهl6ܿ|3?S˿ < 111ݻ*5kիf=7|O~ ;v,===>}B Faa!'O6l`p-+}r*?!ַXlܹs&&Ek4 YYYv.\<6qD/?2Sdd${^~el6|d֬Y_w~3}L*''TNN$KlIDw @x<@Ym-92e{{a۶Btg EO5$]CO5$]CO5$]CO5$]OjhŪNI5(tjMZӦ07mah۲э2N'xNl(.'N''~I"s=DnB~7GZᐭeQmJ:BLI#[X 9&sy{x7ۉvxV>n'ǽQ7-Zy9u¶m4BM4ݺnPoMfIF<$^ ɨDH ;60MBs& ,A,!x~2X04JMԦAp/O"EEE *RhP! x)=`jBIڠPic@]I?ntEg$i3XcbtA2'pux86UrNdˁcC!"~'aq7SdZ%  wnt"WWY̫$#rp8Hh_\x0orN[s5!/AOwr,&[.{yr4`l"J Ù*'*4u0R!JwXMzYefBqtO'ExZ4!$P9čQ_ԆRlސCQFnbx.49ĝtd~ͭm,U&KcabI}R7-G rfɖ](Si26c@Xrק+D o$v <ۆ&z G7ߋֲm]0>]`l Yl B_ȁű==6"s /HpbOM;DWaXfKwgOuqe"_qz +np;>斛|ñ36Y(1P Gb<=iuD۱gY(rqʉ} Z$j,?)REÎ bUf1MOInGm3WbrWN'8<juDqw}gl$Dj˷xTcϲ,^RSSD2YLϟbUvDM[B3Kɺ.2Pfb?dOӊG%{C.-չ|+sc> ::,,G{=Lm{3́A?_:#o|:6ޟ,"gHD X׻tk>,'6ob*ܝ+/Ju2eUNT}1EJjʜ؈ݩ0c Նi{<3:OӬĦ0GofhV#Z-2 *gveE:0#zZlK;*\/ԡ><vb ۃa8ť\"Y[%J:gs9G'wp8>:o_/9bMU?~{{LR\NO*7窭n&mxesYF'^SKNǯ%^9#˪:Ֆޛ ۶k&A]35tԦ_qP\"tz+{\'Ngwt^[O0?IͰl7MN͢Y zbߩMZq{+n|^7~M]M(k(-m{Kfb,rN:w jSTӨUUj E&rDnb7~6Tڽ_AjPUjv zBHP! 9]@q|iމmkF;" ӢXV­QiTTM2?ph(H*'t@{~7aNI5ȕ4%LLDyJ CەmC1k2k0k6XG"#vĈ@7,^4?2D'syd/[ћi^:=Ҷ8e+Y*TNؕ+eG UEn2/fxTO2h;9.^8&K;ɦg cV_'45Rl^eX'06gl(@\mjnέy:ATO* jHm#(|cWx6xw5 U2 d߀{x=ox8Ӳ6XPX4m{ I]p|w'1bS܍"9e *Α GwHtx΍W``2Po@ Ж u,_̛shS?r>llN:_#WqboDD|,Wָ:Ud`odpۏ mx,>cr^'شͥ3EWONi?dP|~GхJb{Ü n->[2~=Q-hho?.<.MM aeόlYUۆʝnh'G +'wU޽]PIE=j=^Os`#RͻmJ]pyBMomLe*ܝ/9{0o!xL]}aF[mvJ/Z}16exc@mXU-q_Hz9& /}&EY5_cw}M]ܟe%mn=fbOڴwL FV?Ob(\/rs^et0ށȦm|f8K䵳 ޕ*L>|t˲xD@:}P`Cp\J\/oGJ*`j&7,x<]![&Ϧ5<32 u_"ջ9 ăm蕱,:ݏ1E] sl#>A.rsioq9斛, e׍WYfpzL^祓 d];$ʪJu"ImgR|p;tK},˰];fs g3.gRn K]p@oB^zyh]Wx=·n-P/uB ,V7W<o$2"[lt8IB~O8 (dJkG <ﳁ\cr߼OPzvbr8gؖg>TJ-3tO^q2{6EDʭrgX*gpC{_: lI#'%txWNHN5|=ébuX{:{who`GDw{]~Y`,ğr8}!frUfXzN4,޺VtCz]&S:o]̑OE7=4cV?GBcC9kcUf0߽2S{O S&:Zk~%M3:~7=M(j俾؞I~&> P&~[l{| !>koʇ }_^26c?rqkTf}am[B<ʞ>? t 9WplKۼ'_;o/[nAx.#+#%c ݔ)^:^|mnZ44 ðJaO!4mN',MS ?=a.פ[]dp8Ya/J0\=Uk'ǟ`X6?|}7WBt?,b0y,.Im2T ݴk~ JRY5<ƪedY'˶4Q?-oZݬQ}) ˴5<ƪ3 эl炧FޫnC}jeׅ`w;5NCYP)ħ <к4~Dy=cCFܼroIkiŪ9K%N-iߧ9;s{ZݜEeo]}`TlmE(nB*&$北:?rŵ-"#5grE'Q4B3,bA =qͧzKʨ\S5c᱃\I* (ْ$yGI?zs\;YLw}U~ɌʙH+!tnY28Gv).~,cC~TBEx:>pWxLjV?UB669jUqV"e x p~eTVḱz\LeQB|4ɔCYvy(><?=P;xgѡ;NJBu^\(67TMluPG=p')Ej )2 :ix\)JJ൫uq)0==$"A˫ ,d7Ljo6ੇ>+564ѰRk80Hs{am jK%A>3g&^&pgC7: [=z<}\Z+yن&:• FGb@-aC7^7i菟|Y4eh @aws0\*2mg <F|d R<}x8W&+~!>a&<զ/$Xbݰ(UuFz圗vɆC޻[c$Z׌EIrsN3=2!ZG3,޼ZƬʉ^RW:6:rl0H@7׶.Tx /ܞhy+6/<1X\qtxuC_:Vy=N>2*k8JvwU^>`O ˕5^@bpbtb`P՗$aV]rVmqs5n|xTutѡ{86pL[oS&F2aq<'b=a_~"A2*5sE>Sa/̋O?tZ,k[#P3# lt̓kS{x?;PmEBBJE88١*u9'+ԛAv j]ܵo-+:ƦRɏҙ\-8ЙVP rdwh b|ƕ*e C!`"P>hx4HhMkB`.[cqFbt0؀ {;@qgElQ#3"ohFik>L9[ؒʨRaӗmC$Wj-TjR~ 7m;0L\LyôIFzclkgz[F[xwNXe-L2ylQ%WjUؓ1c+'NmôILgB K3m'ݴxPO<ږݴo.x>ZrAܠPmP(kDnv|zIM,r ff,D xGo̿)[ҍ+һH[x FJv.o-lۦTȗ+M \.ý>c Bo#! "Sȕ5&պA"%x:~fX~i+ăһD[xSK*?7j$F:rJ]R(V( qdCoDi:ْF.|4 hH!Wa/ֽǹ1')u- <H<bOΪ&FEթ54J5bEhC,&p򹉅Ăna-*e6- b͠P5(Tu URM4 ܄ ApP! 7W MN偷ThOM*I6 ԦAC37 ԆAiW z]N^~ʼn_Y?~MCk&u͢\}CP&jsciQMEuW}{:Zg؝RxNu-<_^̢6+%0uͰЌiaMݤiXÁNX@)rƽicZ6Nljvuxx.ۉvx]hR4xv0s-3/OgW'{}5b폃˴m,s=0-,X6;2ZS󇢭nD۾NcqJ&ktzw&z'GSh?Wf9+(dw} 87w~!>a:S0x,0މZ_h r!P:7g |癤 ewNMq{HYZ<.g6dzp4F2m, .̠V ŮLH/d- qx([Kl^!>k*]6Y9P{kyt2eqkꦈ.Si޳]W˰+t:UIe} xlPmx!BW'r+V7Gpesf80~M6S$3z#v(ۆK %<y :;.ʪOe,OO!`6 e|L2k#VQD{{葻yv7Nbb.;6>2oK F{yض͝2%=̘(oeٜUx{#|kW|TlIsG H7-nO_=juU+s{-և$0-6L+ܞ+p` ڈuf"Wk F3)ܖɖܜ x}Q}׵ƫ5Fb 6r"nd:]xY*4MƆbR\r3GbSĖ\7),vD؝ 2C&[sw'd6x7yV:éٯmΫܝ/(wqKj$P9̍*ɘQ[ZCg:Se!['9::xLָO1-r٥ Ɖ]aN $!]hrnPHa'@"صu,fPg1W%SPLxb4`ω6"es7r}ƝthKOT̿ lN6_c!_/pt$,mKod*8b~ѵmRUcT'[S5ǁ !OodJ* 2ADG<#w@Edܠtc$f?耟^,GoXbQc>WgfIc~iAz} xu9$Z45ْbAT  FP.tr:V:Z IӲS7,,F3,tD-4äY4tFC0 C2zy=F8xm[:Eՠ&IMP&MF7Ltls .u;q88+.>'AM p x=r"xBٷb $]CO5$]CO5$]CO5$]CO5 Lfr%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--a3v96rkrp7b.png000066400000000000000000000256571524103652300220660ustar00rootroot00000000000000PNG  IHDRPE cHRMz&u0`:pQ<bKGDtIME u*IDATxsyowώu;wIZlZh:-[ϩ,哜\%RTJJU*uʩRblv)Hک$(W } g%g8x߻tR!p,BK@!N@!N@!N@!N@!N@!N@!N@!ew¹3oIeT>҄E+@=g\ c[Ã_5YbB!?9ɕ7Tth~qKFY+R74uf?24$l1_ ׇ@H̥Kv(DY,&iu}H2t%Xsxb<΢]Q$se QFӧ,󖯙ԩ%Xsh͵xU٩)l$genL1ϓ kЀ۾jwB-C3۾o-$Ěs>ߢkn7-[.SE[5Csv?K@P@\.jm#kwB%V<ʒ?O#k*?9\_OE AL!VAi<\$ojI_aܚgɟ)A L>f+q#O=fM D+X9h~ZW#;oPh, k"3ӟb{{i[ ! " znj9CC! DrzmZw}ĪʇLҵ]r T*d/05+ A VQ!-@*} !gtnQq5ϑRB4O~Jߕ./3T  3qxi4oeLU݉`*{ Q#Rϓ +H0KqB,LޟSًxvJ1I:W>`p˝TL$O)b֭MBN8~ш-7$.L> x;W?Mſqh4-~rlj/]b)&L'q? kwYb4Ck]ר;$ Lޟ%shzo˚lGM bD/*L^ w{{i8HB),KxӰ%VK|05~ivB8:4o*bvY1T)x|ۮ,*CB`eh|ѺOu&KY|0+~xF. HgM4uIOs63b쥗(xx9  }ݥ$r݉B+}< s\wmQqv)΅@3H8ssPṪ!ܺG۟!mG]E~ wZi6kw'cLqBhԽm z&7nfL2p!L"]jTmhؾf*{ڣQt :.iQ8z>;rit.T4-_svtϭm|ak=QYB##UXCfW(uU U RBk?;$嶧l۪ 8c7DW>f e,< @ţCl缾%Q/L%::\2T5‰ Od DKowiWL1.\I\ߨVӭ >DGY=yeDa.LDk7g?i؞; &_~\t<D6o赡TζލTph(5mbSGy?>⥞ߦf%-IoM~##)ND)J]Ae*xe/tVW$,Kqb>[hZvq1XFh/F@-N?@C.,N\孁Z⭐w*ǒ(^;|~S-nr4/Ȝ?_ lwY]LsxDi(ϮuʛUJ1w62skÁ!6Օ>d7# ,!oT]OG硝Al@NCC-O]_]+ & 5eh4Zs'HgSeLލHφ#&k22M&K2Ρ?ޖClI`Z6tt5q]=z ލTgL5|mo~t'CCざ'Y_!6AhP#tMXuB]ݡ(E4/I;Bum+c~y7#s]-*f`J0l6M~ƚt(vC[Wlb !>xLΌƸ0g*/w,_̙3>>ݞ]Ľ4SDjs]MTPRYJqqaj9hh-zj+7 qX͛|6ࠃFT0DFwieƕ^Z)&?I ITl-ؾ!xO+Vl\=DN>D hvٚR6w[vuWjg'~RNBgvػ+;7g;X1[X*pHb"!Wfl#GJ!p_lgW^SqT$(7w1V~g'bI4g'!PQJCIK/t6_/,'#!=AoT]Hә 6WG*jm^Vlg'zUfѼ^:}VzdqR|>8>o[QW涉l-yr \XS{\RL*A4gQŝ%3&^[zvs{Cd8'3`oleA8{edc#pu[ۺfmjw. Osy8#$Gsi{i?)&҄St46y.;9Y4c|hԨnq`o5I_"mFnBָ̧R } 5V])~ h R蚎6aZܴA9xW-wvրGci24ݲб\.ھ}kk϶/]Yrdy Lknr>*>x-WUlvlt_HQ:`n&d(u,C폰na4ݼ{k̭]Zu_VVkW2n%OI n ;6ؼARWٶ>HWk-Cw4k&q]uKKbАo^u 8y8q7.G[Аp$0lw9BJ@8yٳgݥQ$&3.mMhJ-2'Ӝh^/QЮ C8N1 aX7o7}uwwRw]#}xjXZxmOtTɒ݅M!`Zd:Űőe21N%9ɯ?_(,>DG:cwnAMΙY$cYz7b+u~r\MRIDŽNcfQFs[<55+`(L-xCAK XŇg2R`y]<-~O`lB4z;ض>ۨZe:rkB4yLd.Cg{W{C<ߠ +XE|p"ϡjnv6]+ViGߤ. I_}ޗ)0aZH*ǥفl޺QqlQg6[(cY.bKl0tgKqn,#gKm76Uwk%efAsdYOև]XD׏8YjT5xmgwi`ZqJ>Η5P:z>EitԱ;'_˓mZ/EWfvnvv˓Nsn,͡ab`]Fբљ'# C6؞ 5^hU`^*Sݓ1(>AַIWwe)'>%x], XFԅ.OȴnѨھ>x;(مy-> &&A0o"Pљӓ^vKWwv^1]z=YLӁcwi$3&rB`[42"C#Q.O<;Ȯ uvV4K0MMeţ?L9_aۣ](c.5jvhʴJ+DzJ=7a1QbKLŧg7P,vֳ]]+'ymZ.P&E y;WK34:sΦzCҨ 28!+}]5<'D}>0xԝy\ Rkf@?oϗnel`?A#dwiLőSQ>7;zt6-ae%O R&5R7=fÓOh4 ŇC1cZu6gKw#zg Km "VA0T#LKU47ٵ1D}̘4%x16޷҄EFUhqr c |voZ*"ZWpLBCc}{-rW2"{(}Z g6k^Bp2Ώ_[7D[p.ɳ }\X}uz:qG7.wm"L]Bunbs4Ri^?&XSukIdPG^)vW>Bܵp"0&JkHhqJ WX V_QwV;rj;;3ifM teQ0 tvCD,]fGEߓSt6B$1[^eYt֍f.W,l6tMѴiݥ Qk\㋆iv*qA`&Kidp~XJa\@p\.ࢯ+4f4 :{:.S, 09-M'~Kmx!EzfrU\E,GAp}'c4L݅cK}iƵ}Q3Иo?fw.8S##dblc}ҊbbGw(44cmIwl 5ا;,"71?F<+ ^.nWٱr29rh ?1qBB,eYdJ[z.GA%y!#76q55᪭qًo`w)BT P5pd($7ץKVe%*# 7>*p77cHVL+1U~bYrWE<h93dlS{BΡ Es]ZM7 hK&]Z!A4MW감B,Ke0Mmm>y86|2)IJ9T}P 7>rHY8*WiK+]bҘ* e%|==v"DEʎe@z.GGL qoN ]Zߺuv#DE^uurLdGFK+=r9򓓠:;.G NJ> ,P og'cw9b9'ny.3ߘ r9rs]ZtiXy~z9"2.R֭.`e'' CB.O,<]]h. R/ k,Su YSShGX̩U}̷d|]]ҥ⮙44 oGU -X\ona]XU[ɃdB,,+Q:纴> ,2?P:K+2S) ǃr* HuiҥbY]]hzU_.Y[U{rf cjUTb4nk!*RNzՎPApnt q׊x+VWȬl'=zPw7hUTA0#!jZSU*HP}> LWoWA_/]Z!QK*`~~ mw)BT¡UiLU JҘr i,9 8NAznzٟX穪 ON^65]*5d9M|b:~+@w(Rjk.OMQ*:}])udhn3:麜CPAp`FMe QMM4"7>:[*(!VM]_a5Mн^]]v)VYe?Ӧ.˅QSC.QikonP:\~۲TTe#~Zzv]җ0|>"Ϟ%dnjlȃPA TАB{'A 'A 'A 'A 'A 'A 'A 'A 2XG!%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--cgvkcjlnr.png000066400000000000000000000246251524103652300220430ustar00rootroot00000000000000PNG  IHDRv+{ cHRMz&u0`:pQ<bKGDtIME (uIDATxYlgv}]h!ERn"e-mٲ$34 @ 0:jKfLR(etHB \$e.q86:$E^i1Q,k|1kb׎x+%7?BBYr,ͱ5T?'Gx=\H+jNۣvIf6ڱ6$!|+WY˩=N:"'H ;#=nWWB"N=¦lpF&*=3:t!,m1Q@"vBǡ:=xbh?7:tLǃ 24n۸ x`6:s젗g 5+|>jv=쩪ù6Fm;!$fbDPQucIXC!&32 9 wx'!"!~z擡N8hhpk?b$3˙swowGp;e왁eF-2ZTk34 +y+B_{EJB|R˸]vڢ;{k'eKx]6~=>\gr)ݦq0v۫93fl:IE8qs?Js]JR((Pmֲ% 8 oqT}Bax:͵F礧-FC[ MYNn=|g]cD0@G"iR"D\B8eɛۦ\*t89&de;NGi }hS$d̍$cYB '["8 "P5uϦ^.G]s6B Oe) -M:D^־7wu~_C2wWS&RY$_[C6jG<K*cS f7<2/hj: u^ۣ)UM'ZL(Z0, Mnla-DO{"w*)2] ƛ]ҮBXlO83g3)24 ^e=?vյ`!Q8緅0絫As&/!,r0'U]Z"Xϫx-DW[Aȝx0&*%l-YYiWQ 5Om!MQR5<z[ʌN&gۮB&F[ޣ1"[l aVkWVW4T-Y=ٮ"fƛ\2Wh aVC*W3 &?cw6'?^vObc&3Pgчm_r;nW{ls%@#6/>3?̶/{`S~8;3{I^| J|{m:A}0=q} 6wXMp^{I ;{I8=t .SN`w- 4z[ :#I\Cӵ|$L\cq{lWWQZL}uװۜU{*;$X|>KIzPչ1y !l9?b!mΩBsg\շ/"4]N#(1!h vS֊ '?7+ttpQi1,@71ۖD`ҷȪI9;7F!jnb."-{~issBU-JZg4xpFf \6kF"DMUCD Ccx~įTu,`$)DP\Z,秘=0:!jf,%%@kPPm$JL]I&)'y~f vutƸzVy a2J{9=nNuF&׫hC݉_isqpmű`?9mat(BT`:vBѡ|O{4%X˪lO-&Y?%Ѝ]1_{#HkF#D$sLgFiwPK!_o._y{LJGg`#|:=FBG]6nUs'^G&OѡaI60q,Hh6t8'GdFX)Ll&3B0K[ԭ튃@F 蕶%*Z'D= 9cFR6|0i"nh&>&j$j2:jrs;T]v$wK]F% ^J+L;vkjv,݊@/J_xL&[YAzj˄1=- &oԤVdV|Ͼ:<>'w I&3Nѡl[kUJ~jt(Bl'hyps;ZPK"0<3Q}p˸l^o>DBzG8'SLeYlLB|cs+CbˌzG55y:긽GI"09ZMde6z(11:!^j|T±iKLYTFҟv7v5+v5r'y^2:!^LK 2=tƈx[6$@5ML[4E5X:P*)OJմz%FS[y$)*ԻjP^h&3NWxE%"ɎQ֊F=ohɚfrs4x=S;Y*Lp*_YDAF=A| ǂgE뉼aʄǓ!\Uٞ$tϳ"SNcƒvdM3s`a1\\9qOiF$QCm=Irlָ>D1Pge~_rY>3Ui_`RM!B0'~By5ߟS,& }8L֭[[.F#Yw´!6j#NL%XLg<{]]|v?;p;]]]ٟ'mQ}'w1ESv7j$+Nz#X+(.&KJ+]q},!ל:u1Ūs6N_=2hc7صUm2wMӸ;F8ࢻ=F,1PZ&_fx"R2]owGp;em'M)}1s5%(ThܛI2Fuk1|R뵺&f??@gH7Ωc1{FYx0b|nػ|_ӳv6-&\3ZnW8T0}~:KF*Mc4^D?@%z &m Bh+]] # eX{Q'+'Ms\ZNqPobum-uiW;P"p>;qR ζȾKf =q9mcl_j|5{먚NC(!u^`vB$, ^;&Ƚy^WoƢj:1\щ<QO^Tat*rp==|n)UoEUtCI6(-M:Dp9EUuΥx85zteO&F/??43W|$ɝ4TMgb~)*FkKQG$M+ގVqr.yY02XR\qPjso?#/:Czl!YsNaD8BɅN5ri"4޶ JR"q"ONF8{2$#|ɓ'f\'W xtGiXB%)1<'^Pxxs8Rݩ'MWR|}oUgc>rJ*S f7Z w/KI:7%y a/=Q>kOJ3I&Ѯ%Mt -9u$b%o3fl*IE8R_ƈN}l>wѡ`D $?C!}}8#ϓ0=˸]KK%7o 0^\SF+Ȏ}q75xk&]'="v(έ(͑AT;GY0x"?`WkKQEoA9l=3MiiILg]_Oi%LWUd}a Z@OHߺ8BmK4 dGGy/\ c.{Ou(..܇WeO0=D/_h. aO`m6/-nyӥٱ1r]=޷Lr$>?^2N9"Y"إ)4?o`PjPQiCCp@o/]XTQZYa]B96ī1U"+_~W_aR6Gjb_xvS"3:t}M}}ȫj4 !J@)+fXwVbX!EEgEQWAs\[dSWXGU.jKJC۠(ܞ=jgek!(t>JCo5aKrfX!V[>j,,V9Wl,seD`?,a{gc6EM9{rGP;h1ar{* CQ,SƲ"C\%lbÜث!sXd%lbZY)KBXiHQ!c'7YU^a;JlXx!!w5e{MMثS,uUbt BT%ǞԌ),ȩb/`YfXF,VR{efyMlM9%lb k1#Ub/ܫ*EUc2S%ӟ{Gټ#(B8?OaaA^ )gin`o{zp54}LRY[#30@) x y\ 2RŌ>BBTXRre&&p77S'L6Ui7nݜ? UeۺS';6#zǍe!LAMI|9;wpȌbs8H PO $]471Jw DŽϝpBNqqի2P^]e}h5&t,w.P<2`fcj6Kfd/4xV{+WP3Ǐ;~n|i.][ &ب+j{8abￏ]RtU%}6O>@g'Q ;:=$vcnjK&Mk8c1/aI~kmvR#j.GHߺ#%Ӄ+޿+..B/u!v"k(>UT3VWwuxQL8WP}0>F vp"n"ﾋ#0:\{"lʎ~J>g0:'@!9IBI"B}t @?%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:27+00:00hH(tEXtdate:timestamp2025-07-09T16:08:20+00:00IENDB`doc/design/images/s2shapeindexva--ddonz2lz70r.png000066400000000000000000000411231524103652300221470ustar00rootroot00000000000000PNG  IHDR=qL cHRMz&u0`:pQ<bKGDtIME A3IDATx\uTι3 9$L"l%˒0Ϛugz,ϝqlKcSA;ѹr:uEQ]}PX֩:&0 G0{@J B@ ) B@ ) B@ ) B@ )^`IUT%|U\U) ʒJfPS4T@Vt 3n4Ә`31L`1i7㴛8f.3>Fcb2S $ZKIRIyDN&ɕT,&ˊnb[[ح춍Z&V3f5@7FU YՑ Y7QU*BER Jo#p0م v4BeeVRU5Vaۆ vٰYZi R* LRRSs1qvX})!Ds5ת̬UHde^AEi쌂J5҅D([pwXԉ"BAA"DoZٵ sU6~!ak#FcP$rU ba7Sn|qf0^R XM,":D"_f-Y!qxa7^삝M|ĭ27s^aUYKXT25"E#de.#Q/1 K"̡1z;ڽ4=lI<7 ڽ",YN g!z_`=[K| 3g1^c!{IȎ=]7p:Ϲ;BM *2WRCJ8v警$~Q Ƒ>M$E2a z E< y)60 _+0ɩz Ž=À7r|!X/ώ Wqq6ɞE͂-54]ġ n̯cKO Rr/ӎ s!R% JM`1aaV-fƼgT;cS1>VXW۽$AѵoWp<`ͤ$)ĂXN2Xv 8>_?LLt])zUuvE?jY)fWfI/#C|4S7촠t][_'9?P_Q Jk2{\NcKF/˖~{1é莳R3Ym6yцd펐hkR-劣:0 ~k 8qڭws{濽f ƷQ'a28/{ $" \޽ÄeGG0sn[;VMG5UCۤ]a~q.kirJO±D_(||; O ֕t^J3Rf3QX,&,fnAd(, L+'#^LfB_R5YLUxp=/5PP4Ke޼b: l?#jn-k̮UXX3'Et޾wO3u{9&2{JƉ}vV_SȌDV\ eI#]Y,p$HÎjŹ" F< uer'Vu/0.3GKD/{b[UL^*kxl ލ":a1!qr*#Z8a;/ {)&tu* }\vjƇ73ca XN V.gc la$Lhl nѝ8ܼ|"088g8TUQ0^H{)&Tѫ4*pp\\g7g+caZ,`,E1L\'L vMeOV@Qfnûpu.敌a4MӫUd0lfs| >$DUVg܋vN޿kR i+&GC;v̯9mw>[h(.6~f^`4n|<K#Nl2uU5^ Ȫxt+ JMcz®lUl,In]KFqZ;~OD{JCWJ ] 6Z,&U-uz`o?ZB2WATLfnXC4{ 8 CCT|]"{At{&mINYIp;t^KˤrE:yd 23Mn]u1=+ui]̭Uٿ +F1^!tlwL<[\gwnW\/5{p˥zQI]/0*dJ-+3ͺɪqe6ŏ}A>ˉ /DCb>n-U12ؖɊJ~QU8Nmm;UYbx}ߑn!u2VnlmjH)0`Po[Z,C,#2 XM999z~pnc[juc`_oF%stƕY.+CMѰ?m=v+[;qreѫ:Kqpo n,$$.7w.(z1͉{Ctl܁mM]3U̮Uu~u>ԯb˧eNጼ 3MEyƟxWj:#};s|he*5jv+}AaSh+xv]ow"ɼ̿}R|Y/^h-r6ida5(8Q;0PL/eYT88ఛHْJ˳I mKVW|rƯ?JёvU+3IjKBM˼y-K*p|_nZ{OVEYXX+pY99ebpۅ~2n&=ɊƝ,2G<"_eVe2Z09dKf$/ŋŋ^lT"69YNIl^RApTi4a0gn} ffߐ}CnjΥ"o9906l%YB|Q\IqG},$^a9!Hו+p-_ ޹&6CloEg!Q%U :Pm{{ IH5LA++HC|t8lf(cv޹j͟o`pn_;[>Hzin^[%ȗeF\Ѫܜ>~RrHNs{_jFXar ^>ĚZL<}0_}bԶ0%\UQ뗇/&g0 ">Wc-=NkӦ™LoίW>Ӄ\φyBEj2cy E .L)j]akcϞdV)To^ʡ**?~6pw]Qt˳IUk FoDN2כyq; Ac7j=k([]f hdgxxo)HwReVESf0#!Re Fe%IkH.a\v{Tv{x=ٹқT^۠#^E7 .܉3m||'A+ldE4?|:\>PZB\/Si8[k'Nc4nh%_޶<$}M9E 1:[Tj_迳ȸPk?|LI$5&ڛ]t5`Q(hm Ez!zan5|t}= pi:۱%Ec-UyrX98?ݘ2[Cg2mJu;(f+K5Whv XrW_ƷOqi@2k %tcٸ6 CݢWX-f4t\O>r@~o=Sx; >]lDN+nn![H﷗R̯Uxj{cM V(kpʸX:- 5 m.>6JUmnw.]Iw9<ixp:䊽Ypn Y3WU^jJݢ+\ehrOlͶd҉g+59 o_[Q({7s{qL3\"DNzGQ;8VM(2vп NA3%̐F29"p΍ go80a ۊöa))̮VT&pᡖ+B|Ed3aWjحB6z?|uFC<ί&Veu]^OneUdFa27 zsI"d3U%b4h:KYVeNC_YJ ڙv Ū][c0aX衮ĩ|''ok{׆b"Wiv,iح殚Yʽ-z.;˗pwNo whRwoЦj|. _=B \Y!%S ; F"% 26綊nڣzظ?{?1yuMshk2ߎ͓u/638td?_ԣQL )nŤDߙa3m rl‘0n{uft Uq7OhwĀ?aۋY3OrU!ˈm8mW*-p{B,YGaдuDL&̹۹v/~uSC+OMO _Kʧb_PXUhIe3dPn3y3.SҧYlcങXfv ko_5^q/^?seţ!ߗ<ԣxXIxj7R?8cm:sҙƹ,5c06صϘ:+!^swܝlIF?3j{%:E/Mt-zF炥xc^M7,n>f$-!uc1~޿JokZ{}>|pA=~9vyxCc~gnVs#zr+EO2#KłNf0``$G <𚚪?__!UPaπ.׭H6Ǧbs} ƚrjϧ v-F##">3 ( g鳳80/0s+~w)Mo#̆>dϠ]Nfw}na5/sca_T"쵲o~۶ElEՏPZLDnڰd ﶑-x>Tux|( gd!_4c:wV=#}F\}uDgÞOn]/^¿ͯ]J#*?~v#j~v3ܡedpץ b1olRSOkHDfz^OBvZ*Ak_/f`١ƽ]Gɼ+R=RMߌbvN+)UPW/}N2ce5S%.fg7=l1)o G&7lmanby?ZGbwɳ1a7g5Yi_"/`f3f%zb6W+yeC  ;ymU5bU%UP^.c6slS= Yqt,̯'ŇI~T޸d}gԽ B󪦷 a3f+]+z4t;p`Eݢ[9G l *&L8N;db)D76RJ<{(7l7K obVlb0nɨNE7 tcrc6SQU޻{"WVqy%ns:͔k VS%,e8-LAqc>nXXȍbnkdZu+՚RRb*[06Şl}O7#+:.8f~ U4CRۈro+ S#g[yfFzsi6 prsk^a=]鰒mLI NDrͺcBV4\۰,F ~|keGˊ$Lt޿P_49 /s+_ed|n;Qk\w3Ǟ`u%7x #REݢڨZ9\No+'#2:YL(DmyD'CyR= Wd6vR=QHBNl齳Z^PR&[ ^:{|~6 p))a1?=SX,mO,'~{I zO 9ۃͲ͓;n87P쎨Y^>a;[VWN0ShyLM&8<w3+ݚRD"F8ǞAut{Si^"S!7xϠĵֹ&r2K)؃A=A~~⑎<,U7E[ؔM'r4wod[f4#//cZɶ~w˜.pr2#Zn+JOnoM`J\+VdÍ`s&~ۂ7f r|_?ΫR#|wUB'p9DU ;Ezjs@*5 q-<^B3+~e.l2qjՌ/ε{k̿~Q&o[*2l9l )KŎnYݜ-)ms[y>~ g~9cZ̜>4@:j ޹w398@׹nacқr2$Ť?oʦDﱂfPwM[}ŪnA-DXn4g <}d葍l2d߾ҹ߿Zg' XR_|UX[MWdz]6ֳgjx\7aC*:7+,ī[~{*Uvn w8cSQ^ލ75V47rV ggS|p'i{g:wt}.n,5$0 ʒl!772 m/%%ʒFŧo,&rpqo.  lح&Ld L"'t2dسc23`׀":^^ y7w-$Eg1!q^{*7gsrf-Jfw',&oJ6-zCaooSU֘]β*rXp̔ ɀk乁-v9Xug&iAXXYH(躁Fdrts|r{Ufʼ+ C~aFDaMȊ$* ˩ɼL[ pjɖ$^e 4Mb/`'Wo-iUW25~{)a2sboCwry6 <5E<f kl0mxdo;\)΍A?-j0ZөM-UVS] Wq9[k L :@qgBo4hC쭒-J||;~ns:lf;𘗟} W8OnL#]NI}3GMXi:EbKg2xE"WeW!RX Ƌ'FHZp~HUV1.P\;10{gkLf8TR;t#)fND#c~dN۲٭fƣ.3zb7Ӻe&OrevxU';ܻs~?A?~n?8a:<8f-]T0ps FgFεRUa-][lbYT9qvfNe[֞A| -e#w#_~!ޑ`4ddJ#?tCccfu'm&YJ0Zه:˪OfvtV:Jӷa3sxRuE IH%6>cy~GbS__"BY҈d>e4cSў.g+Fmq8ZKб,ƋbKvh SٖfY8}pdΣ:Nɩu9P{cA;#ɪ%v/Ck>znѻOEH8SplgG3}>q4L">;!;˛(_< v!::FZ *sRlmpw5nXiL*.qr) kFm]IIz)M0q2`%Ic9Y#1ahwTl{+CXla'2S5 ŜF`*qw@MјvI_ea3UY'STXԸ|Hԁ '?Ʈ:N4Wdh];?:\Y{gݱ;ZZgX)Uw΄s)"^3 s^mgSnrsi&)H<[XcRfx5DlwN2^H_;a~ CXcQ'R{ܜI,s{!Ïu̦6O**j46R;%Q5>{GaGƸq7EDHڭ&{n8'x?"z@4;Oѝei$;BָȬTpYiF`3E_m01A>n 㴒.4A)*t)lfDE/1pbϡQ7\G"NT\?}K9 ?|&Gctx4ޘoQ5!|e0ff$oZf L)V KyqR+@xD>$Mw.>go^o^Ͳg(@.HdK50KY\/:s[.h,-7À_|'_58?Y25EUu*-vf|<;Lb素٢B$dp3YËbfS:Vtd+OŰf-+8;3lwgw‘}o_21dC\XOZhу|b5%s6fe2 Nsz*HGIyZ%CPQ֙2yVy~ !(>fCu- ksIjʏ -=Q0!ׯqr_cU^AlT0a`(_q;,"qޭBKEOQu.܉wv'yts ODkmR/c6pI9$6iVXА,|t{A7_;{"wS?!RI͛7P5er*]_NGWl__&8ws:N*/o⩲$zw;c{뱠~V`Ö' 'UrZp-x\65 4_d Ҽ||gd_2M ]-zaDx,̭̇vLyr.{f hX 2^]!6%NhJVEsIdN٥HRT?{h;G>#Cyr|~ wˋsQ7ȹ[98;8m ,88arMmE 25.t'&.xItw qw/'qmӏ.Bۥ&k,%՚a<34|KkwW Ly@S+~vaw.o$(k 3)\~<"  eG}Q Y5sd"#nNDtfJt<]bpFo_2v35. :À{"3Y yhH Fψ}$Y9,7`|/ JH*/qn+'ĂeD*y']yr̾ c1留)֘^RU^<3h-gE>k9V5L rg86lyAwײdJ*EX-fl\<I̘@ ,B>zN3kUF^Dg1 L<:O82*,mDCȕU>R~KAER((uL{5EbE*5WDC 3E eCNL 35.-r{׳~570HfKg F29:A"Do hBʍ2k;aѐ sgG6UIdʬeD6yiـ@ mM3WY2b6C_E4&sv^ÀBF'!KFtDT#]tghS !zMD 9RJFBU >AkaohAUR)Te e$/*HJ4hgWH]` DTjL2W#QPY nsZql6+v͌jn5cM&0iM7QQut@VuU!:Rj6~;ѠXNke9K FR%S4jjhjo*X`1 \v3.ӌn2w[ d2z2qϮ]?Ô}} e * *쿓ePqd&Y%|]FF쟙w3?+U0 ԨIoBe0$. d* BQQNe@ dJF&],g\r8 ˉ8qk&}ӛȷ~{5h96s$3RL&"9q #'~DUA^앲8pZ3}U2j |TVV策$Ib׮]|c[у_6b1}DE#vE grbke]M,.̓[;t(9v;U%$RFd(cWn(Jm?AtnCY2rckJw8t(9DeS*jeɨ,SQbo܁tҡ!<{$3W"a&V] o[낞Tg1ūbY?iT8# )36M-wO&@plۆf_+YtV+YqDQnD.J DOG3RJ<&xXS`pd#EL5/ ܥ grN Z۷k?t(ٍ,;{P k+Z԰@[p8RLcċ*;TaCZ4ϡ0UoTύ+n2t_P{x&CY6+8 ,+U&<$)J2q*Rp:CY6A;*gtgd6\{(IFRZamH/,GvehYېjy!kN >bYt\V=Ie^8nE;+\rɄyjC,LHIk7`(D"e器R<#e*u?2!L\41U!,lYq4@MP; 0hdȁ-k We{dK1:";.Ĺ[VF %RN-|8nE=؃?t(Yj:NuQ0|ME4%rX\:ٳP&UeNpMĵkƃYVsZ z;k. δ$-RC#C"q8txA)qW'fDko"^ qJdcsֹpg<ɾ_ mP_AS:GsQRP2,JTp?%ܹ!mE.sr}hk.⒙%W:V%Ƕm"qеE0FTD$W!*խT&]cbG}caJysv4/ q hvi1Yt(K]je`X"(G\R_1{.up}xQ".H>?ҚCIQ 8mEҡd,3p'C푵:Fq 9ES)R:K#^ʑ E\,');s8 7؁[@s VZPiLv+>F{Dх2NÛzYf84NHLP2|cIJ=`cLě l[b8wHP2]{+n{d۸y|ZRD]ą2t1w,vl iXUhE]eȦfPk%و"WP2M5k% nC5u8_$=1V]whQѣy@Zt(i3P ط\ą?ӆgOad?up̉]&)$Wt('K,-%5^Cy"wۗxvTNM98v@׍*S:G{:e:C 90yMCI{"1G6C*ŏ Z].< ]'66TAPVjohFl6 qi˅#!mgcbip{Hꗘ9 qU#"kP-6v6%\ĻF'K"p9ɍ v wb*'zpV=\iq!"^'v4߉Ѝ~qhıEwCw}{=,.j;p@HҖc;< ʔeHu+T/aFJ ?#!F[:F4:Q%P]B/K"pɝ "^/\ĹD"qsyEIM3֮rr?Ƞ_s1@lhX,[w@c6c,\ۡ?מ ހT6}.ۉ\9Sn!SQ4_ҡ, P}B Ν q&$,55J"uQ\"8$\$'zPns٩.spi P@hN250Ht`iFCYq$]И6nB/L,TTo ZV1ƒ ? V'UJ䖿2 ZJ (J0͝˹qjop5DsU(t(qMdkmҡd%=EXL&rܨ{8)am׃ E.сHk7)",$C{1mڈp8t[)#m5[u8ގlu{9f2h)ɳpPkCДBq8wBs\Nh=XW Es>zhtMTpYžc9" !,,Cy1n܀.s Ez#ui]qYrCZTڑ.hEj؉)rǹs'KPM+ʊv*NPRC# L^.,L=DlSnT^ut=1<j*zpZ0CT w ڣA${bMjʜ'QBWYUP2!AEEsrȾW!DLĪ70  )Ͳ;|˗@R鈕T*Rڐ27B٤n_r, /km%~pg_MMzAAw4q?>Z6T> /~9<^9槪AeMoŔ-vbԴ9k2Z6{ Ml-$nczg +CuP$":;uvn~?. iCQbD:7v='lY[ |.xe?5evqZ[Nt.*"N"oR:moŵ1C)Wo:x1,ӼPaB;9-eZ u\)JFPVpi<e{P#v@[Wە $V ymYPװdp.ˮ o o˺RxrD(kaGnlX,*ҡ'VEuEz <` Ein.bzN q90*⋝#_ƭRBQPϚ E9}TP\WjlE/t}'eE) =z|Ŷ3ocPtϳRSfN%¸ȅH "Nǹ.{TJqNa"*.ҳ0||OuiD.b mG)}$=]ġp0yO1RBQ`MʂzFBԁNsâi3p3C3qpҺ-v!zZ< 0I=[O +Mm,OK S=.\Do` ֕Bq ±n?G1q7Ii4[b0q07v.GґipOg0JyZV5smDpWPpqM5vL9{8S4|5R %)}~{%6vڳR(< D;ݐ^.t+];QK.R.n<@D^0&^7$Z ԖY[O@sC(VUk?xG(,BdXEҡЭDsZCE|-y\8z+G{(v3kâa1"oCn0) bpjhr~"uŞ9Ie"o%6%!DkETFP \ǔeىIaMХyri4j)S]υ0'.xXoV'G7Foٵ5=\XBovMBp0Hs[)w3 jYa#|Y/k.;Cz\8ыIJ4PC.m ;feJN3q[)tY[jށ+KXH '=e qwx?m#ew-0IzF u%4&ۜʪ<|U(WQƳ=) ]zv}B%crV'bE^WG >)˜Y5ƜV=N<&;hCZ 9ÙС)[W1Mlf,͛BqOGlfF٪P,LJ8?0,ֽcمaSCmEƛϿԮ-.qFc>ܚ=\T,ǰݞQ\FU:*ur+DzO(֔;91DZ+V ؁S,s KʏIBq<bg^飦ʞ' ̢T*QaOs'jAӲd'8;DƊ Cڤ2_4jX[gM~>#ήoI'X NӲdf C漏oRBQau|z*uʺCڈUo p0tj8EayϨ+DzS($.ѲށUw订U*EUt,!yn CW1\N*ˍFJTpy(ʑNof?-E`HMZJӔq B * tO#z,.v s I{a$0A<һ>X<ɨtx1lE[6A٨eSukn _Q_ncz |%DN!5P&Ӊ9=FPJ,%02j.ұ˃w2ls/]S~HC}'D*>bR@EP̣fb EՀլp8oH]1 M-d%IbƎЬK[ad3BIR(VItRʃ\tizVokOMq󊻈+؟3F6 =WEtDiMҧa,op[0L*u7ysp+(XY[Ġό.) "8= p0Qmʸ!33H 6⛐‹|j!_eij4=wbҊ}*Cs2۔>rλN!kC/fJ q)b[Z%c1{&'/ +m65?}}g‡ݸ;#Øb0:#_EpS+D[{<<`):-vG Gbbqv *mpq_h&HpH JIV#_A@od8uRI/eQtr7_*BQC<vPXhilV۶1_tNS9F'{qY94 ]Z޳;!āF" a*M qxQÇO`yhej]샀X3"cz>EYV6QNqvoQJ1}t\RWR:Ym,&/yxʸmUG6cQ)z5RsWưswٌ:]፩}n=Tِ6ak.`\.z!.ODUIZmx(㓱2ٳCO]Lq?n\+!^M ޯ!^eîi _U'(=panKTrup0..q2}iS r"0޶?2;QM_*y)!3).Mi1ܸ8x~ ·r'zR M>wiCz(־ Abeݬ^̙1;:V9{yMY|fk]XM EE t#ےзaۺ5mñ0x#8IߥdmY]hbuau($a {2;U(w/*g)*L+=|:j( J.:#>&h{/z\ñaNFv'kElаR+r+=*E/-˻a`+4pgZemqv &qv=hlcԫ*6QUx(KY˔.Nv}qyMx(TIO|TcD^t18Ŗ5a.+J2j/$Λ Z6P]u?_u֖YͼPT>/HumضlV=h9X*֥d0x5vҢ#_STܿ/yH9p0,3װ+c4 %PFgjn`yDsgL.ǢK2_Mڋ#)n:_u-YmYǍ er[ИWvra|+;Xgxd%;No\oV!0rer "W8 Q|wT:7~} (WX Z⦹s>^;GIu .+AӄѠإqjXq(յ+cHGppq3\bI^̩&)ז9t7Gexy{ZSBF&hu=Kk0 Q-~E?`bf,KEL)c:v]n] ~ G,/VmR`9?o8oeUNڻGQeö&)4TIo QN(m&}N*ٍA~R|T[S"ϞAf(+v>Klݦ%}Al7{8!|U<3;0xGcqyde+#BbFcٳFWQyɔY}\ux LB nͤ48w~ebӄQإ .En;pmΔYPo]p.裸 &zJEԹ(rfk!^hQO~Rz~&9K,%{;Xg%a# :hc$@-=K[P&m\ܹؔRp0Ԭ㾼౮LK3Ac3ix|=uvvyufjʝnו;9syklL irsᔞЮdCۄ0 V\kƲ2N'K爭ݸxϴaݼ Œ181ٱCbWqiPUjۘ ݤ7hs3!\&j]#]&t_CmGC^ƥ޹oSa16O柃\(+4Թ\OcR!V90\,uj]T۹YgyBݲB@s/=e k#*CA0ky|-P6~B7siMa@+R}7 5lu|2KLZamn8g{?.ʝXkV99{˶5vcSSL:Żspщ1$LN(zܷMkټz5Z bk^ݹX7,=L NA˸5[05.op_3QGq ]#%Ob]đaEjz|1'&&LJ)w8Q5@pW&5o(h=xX6qE>|xiբøogD:I]Xp W~q+ƍPlpQjiÙwm5l6n! PAk8O'r+.+쩽}cK*Ɖ⍝a[OB.V=K(~w%{E(Z 2uI2OxP]Ͼzm] ݲվ2u۸ueBe.A`1jxt=V_P\w3qk1j?֧LahVA b 4M*+DR()qpwRu++1XLDu&D tgbC{Á F aliضx#8RdS5 /wNe.Ab6$:+;?u< ;z.rqZ̳~7| v°!3Xi q9|~JܿEќ:f/JvET'uGn!g1&%:'PAhy|Z۴xb{P1\ ؇T-!J.% lF o줥㴞P\n/[V1Nr$cD~GRFaTQo{1\aVVMu6:lpRH 25mDu[] auY>zѨN?o)x>yU;Ccpη̹pͥd! HQliq#@k  b/Nk]"{8 dWϜ% 5EKw  A#\;v}5&+jPEu5=􇽜9H f)DV5Li67͵NtxԂ bh4x"mvg*OC[,s EMNjlL?yv,XS%[X##?v°Y2u,ы9M+~JFXNhK'#l_ Ӊ?hÑ.ͬ3~RC8,j榥I[ǜbE-vnĽeby-}\9?D]l>nŨ᭛h O#!=z|_ R>A ٕ?K4Elpr{!:! 9͘+ɲ؄ 0˩2.m#f9K! b7.Z xCϨm\SVViN1>YSojy`6yf'{l8A[{?NɰīG!^@uشcXx/E"]#:=MI EZřˣӯd7nhYbW@HF oݒpuK$*1;?L%v% dpz;j|Dxj5qO@k)8TWkR:C%\lPc6ι PaHMC`j1%:ʝB3"qeh8Kcx:TPƸ̶(W"}F'Zm]]~?K{2_ U9=Ǭ@{› F$Pgc}ͼ>Ljo6JxƳiƦw)@D2/8e5Φ"C?|2cxczxكY I%MH Vxrgƛ[}X7PIkWXĤ3ǹ2XPH8@GS|Ll.j1w.6۸ TTDv;1^v ;> -H2GPâgl|IOjF^1S5hRooЕ5>F1 pBL(| z'ټƻw {sk ƲD"C3Z&(`i,lb}x+g'BQ#bjyH(`WӗMR2C62&PU\=#<8ЈcB(Q8{o| Mf\F( ×jI^\@Va++fؕb;-Ui8?kS[F<&(*XbV`(Jwa$ m ֔>,gODQPc 5 ,jb"3co BUb"8ebia8^5ө(d݇-E`(&kWӂTPE9e? E!X0L0$~ Hg6a[ԉ2JOfnV'7vm9oBQ /,$oUV޳ {.L IoIef&N:w]Eo .O=+ q3@W_BM Ch?ꭶY4Z8#24`vѹBoV݂Ts;~#7߶3k^v'J%)X]emugPܟ)0UdQ-זB0ϰo2+O*l&K7soecXoj06΍J߱אmBq:7ip0ơ?7a)EhFbv'>)Bq<_dl<Αq:p. 0Q6R?A0"dPlw ֻPdJ SLaXƻvb1޻Ѕ 8Vo{*3>/(1sF=M%Mrvc(PK° 2!:}}+}Gug2W(~X <3ە>5s#@g_<. tzi&qUuo"dPlz (9,".]3䝤f'va3ο.yw˦_֍N.U & .i?\ (l1uxcB=1cR͉.J?2)ݚmŎ4hpotdl"Q7! [6OÄBQT7!;3E(?m )9,efZ&/w, 'N=Lb\ef! [$8LL xvpP@Pg ca=LRB0Ԫf gpkhp"EAf0qBE$Wu=L,gwtMܹBcURh .3 ܙոK~l^c⾱y $]KA-(,À_HWK7ƅnsGFxv sb7pPjf -9GӴ(a7([w}J=SbU"dP<<v%fnb-y]"A&"\1J8/$CLM-zL茏 f.F'7 eIҍ 3l)oz;DG"dP<4 vo =Q#qw) 7,J&΁Fs0oM) sĪ7. #PM-/ye=E BOB֭r \:{d."bnS#-t{S(jZЫ+pF c p0I𴗂- D]Dpg2S(Jizzws#Z%u/|SlY30 ,[xEbkֳXj)q ȴ0OPa=drH8b~acv#BU-^$|._) a?'^Nlc6/lt* p?xq&ZyP75!)gl<Ɓ}e;.!L&^9ҚE3Ѩ ̨tWRCݹܧ6+@U}` ޿;293"Y{Ĵ×&ɯ2-KLjٌZ0:\~ *7b329?׃)p=b;kwi='2FDq&nm {ȷ(XFqqBC5/k&_+V~J8<,v:we69I? a|LavlXX\t1F~UƦRALV{O m :3eEOw_ai[͋s&z[y`a|E(} y-xB( w"N[ )r gH6.=LVmW {E~Y\ę)E/8)0Գѳ AtfH`gs=AQD~&"S4.q\U`k"n]ę&s[8k؜߂ Ep"5vjVnC@Ջ=W'NHpL)v:BѦ@یV%&2B;t)˷0QؼD0F;m_CFЦE\ʍg(269fp m aX2q"/9-=LRTWV4:K)fP|Y5loBqW*˪MzS\ASm][K~lGe@JEo E=1v3سL(&h=麟w+lY9a8ilX&1mXq&b:Ŧ¨B1Wq|=K.cI_ Mv3 q~?K-rVi-1'x(̖*'M5 ƮM&qW[h1zeOe]ę8fJlq.G1K10Sgo<~.^Hí+/ `p$o_uMv|/wbP_FO&GE*],8J)"Xz|X&0IAM%Z.=ݏ^ E`fs172|X`>?PmVN&öɹlad.b> $6-=Aױkg )־je'Yҙjz.@W8 < 0I;6`4`݇k]ę$Gh(*,مQ,=g煶AMqb*ơN?W)ypr 2{'#V f sg0S(JU)԰ӌI fT$Ƙ!Rɩ(jlG]}}|1 )p.J\)NPom CHS7&xj:'T79^E\ęhUq1>{Egܶ2:WZ c#`k cq8%yRP uN j+=bRE,>{YcZ*KV*;={|#"L8c2"e4xpC[,iu~÷sQI1\ Z[[wo{K_#&G2}b[Q0O^:>µI.M}=DE(/ O=Lbp<}^-F z87ga0iFxs*`vf《kC|g CQFfIZo m{sgu%rw4+z qSs>`IN%fY<o`(J,.c3wT}-ġoO¼&9C5VL)}4f 5V@7~aҡ k^گOcQ֪i#c(S}T7vAx`UiR *jdB !3|#(W֨hi#!syZIրވZ҇;E]JItTFpJbȫۣU0j MLJ,Ű%k}^)sTݭ^yPzu"Fc IQJ(9@&ll)--s(4v6Ԏ}YNݧ!©ـ[*!&̪<Ώ+LƕOph= QKE-os) IX (#Iv֦!̨&t[ʤiFMƤYG(Gd,{/1+Pf>e*E "<-9<L"i3>z'qRfL4*}p,uƢ}x' H#tC]Gc,] J}c6֖9ѥ5X `Z"߷f DS_xj'15Ju$Nѩ#딚ip5aӋ,B c9?]}AԖ?_z}l]kO{Z\ VQOI$%H$􌆏Qdc%ܤz0cj*JS-k97F&inpRƌqq'ɺݭ>?@AcԺRzR#\ 'v=ZБ&,w/Dy7&(Ui+ ۱Wfrum-"ΤLvFFe@"#^#|ڍ((E $| AEKB-(#oY"gԁfnT VN\ę%EJf?~}=&s'sϿM8c):{&uѸ6zyxK^Z.+oLRp^,*#gx{pJO<I>BphL(f9~}\ QQd q)>ru@m*4T~kk:M=QhHk.Sz=@f3q݅2A&*soX64"1MPR?{%{հB9V_&lc):yFbl]`a$]!}>+&v{Tҧa^o Pvp8 C% }l+;Ѻ 6g|EtB~#u]xB(ѠDkK" tZ SQwgEעp5ijipo cQ)q7IgI*! u3 D)ܣ̅a2xƇo gYz3-4>j'gF++T!?Z C؄dO{dMϤx/;Wm Eb$ Ǖ atr5v 1 k?qE\VS1oS?uܺ\^(. &El\cچ!spa[ʻӨU;c> a4R #;9}S(h[Ъ{+>ֳ^ gRp[q8t] z+3~\͙WBrC Gӄ˘9Ơ_ϕ- BQ!޳{erb6p3H &PhiJۥþI:yI2쨶b`a 08YY!c2xևogYfy3[B04ݕr&iKf'cc:Mf CHSW'X1e$UMN>sXPBcK[뼘+_2l4a78_;|\lp&]}>6W:q_K"dP7 yֻv6ٱXjצaL~]VL2ѽߋޡF z'ݭ~ 3b<=osEpLWc0I݇á(s5p<q&3tWn|B&MB(މlpFCg2a4[vÉtg2W(>u<ܻKcnR2 vvaVPTt(Xo"qgWV ow$BQi o;&qK$# faI4:9>6C]ęTJtA &bC(d'q༏k% \ʎQ}`:&Zpfzsµ7u<]WX(*֋y0pXmŒz\DIqVaېѼx;T*()&b?5BQΰ:}cIHbo/a$xƏގ]a0ۥNg}2E~P|c78}c| d0%&xwa4ۚdkV$ZPƈt7bK9GqþI_MMUUY1ex )h*P:Ym ^=EIo}f &,CR*Q_1due擻 IL^gCI*w:9^άpg2W(6e Xn‘CY$w60Ny_,z|l{`c DJp6UQմ e/Bte6W;^e][ŒNMTjֆDwq&j-d tdO:72pe(¡N0|hkv $3~\Vli&8kl"q&s_"_MW(E9'!dXtw+{8[w?,I*3GqgnA\88LJ,lrʚ 8`WzżsgVAJA^n\rPCX(F8=LR7znpf M\4xv"GDy/}77xe0Lrǖ=KZN~XIs ޳ Ob\ aEa;t)v\Z~ax϶eύv$EG̲pn E8g;0Iw ==ŗۥYgc箕:zsP; [smc1/=C_+tL%DczI,zm [Z &+Hܮw8cE%B"pw{ĨS۾Tk$sD{cߤrf CMklAp&#Qzn&#U9+ kb`iq&z4皋8mbo+v`7(`:wGp(/ɰč ޾#S8h* M'AM(6޳"k.V=^t5ֺغƌ63)g|$g'3{sEɭKo:lEZq? ǰ#ۅ0{dK\N~'sn,B#Y+6%NJ1',"DCK)\ϕC"dn?Ba#w-}X2#\T禾̌)Z-a0IE|'ӳ,J2QlA_"~$&=եNW a89?VisNu"ĠP{;ayH+*Xʿ7？})Z! 홑‘DVakj&x"]ę)3,0<饔yƼGVfM{k1q8D֦t(Rcg7Lp0t(iCB(:7؞Vt^Rlfo[Ś3cLvYT:EnK&cJVTdD2~_TNX[pl,0I:kJV$\XqSL[}X3=LҪ9tt(iQ*|!xƏ҈!Crbh(2~@, fbPaTOq;KJMIU0;4ΎuNCYj5ݻѝ*xUUʉIUB<61&FxykLx]ļήtHK²c)~! oO<'$4*)ʒX`;H4e!b!&ERRq1!5VSf>7OׯǨ|JvUcB .p0FctjK}溇Iz5Zw=v[Y)dF~ݏ,љ2{|-Z ^G D R=bݎ# Na1fC^Q:cj%@HQIp2xP>GqCv+5x4acX{I&>vLS2ёT5xtCJbqSG>2*([\9t`Usb'K@*VF d ).2񈌵Α@L O|y ~g&+TF'F_`zh5Ga`*XVPTҐԎT/agag>r[3˅ij |]M*PPҎB .`"HP X3Jȱ#&=P:@KLNq9YijnxXB '42&\)^#MBX-:5*UB eCMLhG)&"2 hmz-Ac'LԠiqRVm7öށƢx:+z:cw0б15%3\R >Ie.ԲU&5MHX(|Ѻ\00s@\$#T{1*mt3>*׊!#q.YA;<+2ߝOիbdYF5W~jWYx* Mh4qRi4Fb bDe!U*4& Z;IT1tj~#F:L^P:"iM"4:x|G!-+*|NP XbN-(BXJZkg$!"bJ uYT:R$ 6%!&IHuc&qr+6s3qlل:8zOPI%\:ǺΖu\z5Z;m>C~\kL;qZk-LtM`I⩶S)qvfɑDVcфMP҇٭pRT@bBsCv$:;#Fx p#$9 `+Z1磮܊Ü+g7%qt{DWcqEhN=bK+&쟸-5fϋ\_` e1 hɍӶ](JZGP9T@bss]n $zݓL2nqw#3:G$8.J D秦̊3b/PFP A}e1-^eK"1zrܙn- 3EL~M*Q)NO,=VAp+< H u07{`BEL oӸhU-NCQLtrELCRx*-0I޶MGsE\CXs͇y-$*Z #U䲃8ZjS{H$v4Y݇h, w*"Z4[v @y#;P!pˇ,ɌwʱùT#簋>q麟BNKv;6iQۋK uI5;%KqӏD^qnI u;sELujmƲڍ {lԢ޴3]ĸXb^>X{`#Ĥ_NCY )7s{Rd| g]ܔo ?9{8 qt@PA% e/0UYs=LpE.b*spxgs2ҡ%:̥&ƻrE\rq ;*Źr#Y74欋͐B ޅD NCI+ ;' #K2T6k&[梋{.\Ȉ.$Q)ʊbB ޅm~khL=ڠTepK`3HpgQTXb$.bsU9G8w)JZa7lG{:".!w <.1pnpom1Cr@bC>2oi&ǒeT ywr\˄m맂C.ˌQݎ&6Kr`{v$[®w(såٵ "Γe_=$eBcb0sM`{CGYIPҊ;ET](x"zҡdd.bhVV{C ǹ~*Uˊu"Emn;ײz~,,Nq`1:$adU=\.;F*ʲR%yq*.+\D3=GEw\f8ZU"p9)^G8t(Njޔ\ޮt(Ya$^]{b7G}Q$ czQ$ 7Kck7cYji]!@ A,B1+ʊ @ `¼@ BD@ ,^ ^zӧOsriN>^< ?=g?Ç>7OW>AZrQ?~ɲK/ĵkז{/]+cॗ^bxx8%/|(^h4X ԩS|_GGS$_ .(ݙNDX ?яx1<;<P\\|`0(ͳ;2^w4edd!5K }˿@v:`~>/H &%Ԣ(Ξ=KMM xl޼~h Я|+lٲez;p/";w._=>SPP0< /ŔqIoh:`0~FUU=o'U=<| _MW_a8D"哟$=<9;w;O|ӯpOO/8Nd~|{.G>>OpС%꼼L _g?E?}~ Iz??e8ooKqz=Їx;9/}K>(}99#kkk)--e޽v9kRH{{|s^}abbJWU4 ###|S^p />>N?yW~ӧOc__gχ>e9̡GyH$¾}G>2=1-ݻwDN;!NsQf,}/H <oz|sٳ<-;::nypַSO=3::??/|L#ArYf3|62>ϓk7M4 Gf*++9p_WOF#_Wȶmfn=z/a4׿un7gyz;CCC?#_gᗖ77xyg())-oy uuuөv^ȇW6F׾>Y$Ƥ$I?v|fJUt~sJŃ>k,˼kVcǎK/K/ڊZKbÆ ass3555ߙ~cOx,--%igTe~_ݒ\VV}ݷl\Yzë $_IhiiY08N qQTT4k̗H$Bww7/^_5xv{󩪪}{eǏۿ<裸nn7ͬ_~gٳúux'v>띵s7K03 8wq} ۶mvwb:;;?c***(,,䩧" vGg>p:Vg?=|衇xxhh83">?ٳgٻw/=b`v>`Ps.Pzh:c޽455ݒRY9[f@:`2혛_XX$8<=&@CCìKccc72T[6?މ nIEضm:q^gYXR&tTWWcfŹex{9{& y饗|2@HT*Z >,?>k2444R|t:<t>dS1??M6/A~rv%$iŸMMMTWWw^> 2xΈZLnw]X,@ee%6m r:JKK~S|?v{nbHL u!&'sbbba2fɼEAzs|-wp8Lr'jec%菰X,L'R&''D"aqtvvzmR0_@D??q;3<IDAT h[;Dk׮OO{<T*EEE~\vmFzkFoy/\|ra20L 5* ~a}ۑ toDV/ʥixxxQ͛9{,ϟgɘ|._|ɕ,t;zxbrȲ޽{uchllɓ={vӧOs̙Yyeee\pa h⡇^O~{Ί t:Y2~=|VqݷHV IQtҍ[R/t( Gf/}J;v H,|[8y2·/Κ"dڵKlߏV=::zK`RO~k}|G8<_Wx7(++ry 6匿;vGG)+H\.׬wbϞ=? Μ93zL&My>'|GLLL؈Ju3Q8ۿ£>:^{wl߾|g?#Їc޽^Ԧ;t:+~~ /86l__x[wnI'//|; #v~~??//y'D"|`0̚79 ynz4667+G!Ow`|}|;g?F??,h4|S@UUԧff6Yj- F_ ZV.__yGo}+mmm,.y=Cӥ8 !<ǏgbbYeuF#7Ñ#G8s TTT뿇 (,,giMuu,G񩧞bjj_|p8̎;?crJKKg?___GFyGTWWϫYqq-yYy͚5?k[!1g[^d2QYY9q%(Duu#lڴ?1{ettNii);ңo}{P(DYYg?nS]]}`]qwZ})++c˖-s122Byy99|AAy39&n2TWWO纺:QXX{tS H̻~3N8;wvzYfH]]???OoN? esp;sf)Z%/ @ AƓs9@ #@ `B @ f!@ `B @ f!@ `B @ f!@ `B @ fBt3fKY%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00/ "2+Ͻ~a똻=@@#1 =@#1 =@#1 =@#1 =|I]) UBU$iT%Iѩu$YC d0( 663NÄae7q xV>W-xIuj]#Y,($ [YbM ϝoyZ0NpkwVr xhs@܈1WQʒΑ!uTMgn-jķ96:ƞa"_35`z$ bU|_ٻ=Ř)')LX861{ À^;~V?[(y0`af sh)1j$#>KSRS:Ȟ:3bn w` pmDQuͧ ǿG־s9zV /i!hKEs\U_|sd2LH%̥xp}m[1neIL$vGrFܼ}<ܷ})-_HXl#/Mwz]߉A"Mt| YQ7p+xNKe Gܺ%_7}l7b<'g ezn+ vZL}!w?roCq6!DXX/o~$Vϋkm9w$.~Zwo ndVa!DAs!AIҺ=gsE߯n QT!?1?M=,Ȟ|ʯ,xGpgL=M<¦;)(h!z Ę')-hǦPgX4Gg"EdMLpj6ZZB=!FU37 {=j1spO̭W=߹a35P NOdJ/YM˜P!-J:]ZGxpP$ Ġo.=&'s**Ǧ$ *W]G)CnC"9X],fgfzLQ8"k%r*]px6 I4;c}Y|p#ەu!hg72'Ǹ\a-SowTWKH&QV3'#$Yscb,K*rboK #vLf`[͗Hw0:#bۨ,ni03 h5ݫ9OD0 TGL}Huk^xiac I& ߯fQ:iu $w^s*xm/f61 W+LzAq;DݜoQG<~Q\' qcB7"\YanCbjHe}1o["Â=p[+UmZ[|Ya1Q݄{ؠ wm-{E}XEo dj( z=-UL]ѹRf2:n!qbKtT͕ pEMer({Eh ./v8ژՖq~n& 2c~,Z7[&+ ebƒ*x>]djK["Ʋ1vd216R9-2#1WBY{A hjq&n&ʬ&K̻E57 %Vz9 :vL 6u'k^PuFb>&[do%x95cYY/M|g `yzxY?1׮U7nXHjsbҋ߽DLOJ,'$&L y5Yf~-c3C.̻ͺs{… ch[ɱp|ǩiaf' 2Y0,^:>\xg̅e5/fy-|xXbtkKe>c(av4rSI ,ox@fجK:'# 6 :U3mX Ux,!C8Z4 X,2Ĕsv7BYVxvYXc~%ÿHSՔ5KY1$uo-ZwOE^&,Kl>RSnNG5ho/el\,ro-[Bi|t;ǵ2'gZv V5̥[ ~B%+7KilVgO]%u _~2 FSbdr&|v'vn޶k,}abM|>c!NMu6+Rd^CqXYt\ YQz:[h%U.y |u.Ipzϫ킭~zO||}4eq4K2&g]8c?#q!o5z;\_H?>q!8lf~r^xc\F\C"'_ U9!ro'vBMS:Mr'^;ɜoXj~b7796;"Q_%o=L"Sf~qA&̭˷ wC<-**Yk 6~r.vqZ˷eKK\]Hw7踗?9;; rUh.a1& VEM3x'qvF=oYKYMpP"WJx3ޑN86A.ڢxa|v/`t^"չ :WRWb G& 0w|z'ApIbcQ1^[J3P#<䝕75pz Wvd[chv?ct7ɪΥI~b-03捣!.M>,4Ya1&r#+J$LoMB^?8峹$좳ap^׏n>7`~-K%e~rn`g/_q}1Ms)<Ԕ_6Lܸ cun;jƝ?}9Q͎rs~YX/Z83ӻ&M&ɹOwh4z6N ;8?!~k2޲gdK5Ry Bx/XVp9x{9˩iotO! x*5";0›GC|9~jKe̓檢^"=T`ީ072膁aPnܣڐ몎m lƫݾ;i3wV\rߒжNprʇa$r>5Ec5Q[' 4fsw%>xq̐x7 3=&ⷱ(t7ñ!1+*^*@Ost܋TWȕjM$sgy8&z8qq g3suY|YBQuJr:_q$zBf3XQ8T*b]8 fs,m~Yzq)N[<0A/M3XIn yj䠋?_e( !rWj]j*shT]92%P40L9>&M&81e-U`#Sa4Hl(tSS7''J5$+$-e 1 |3rtFRɔ9>ٟsb2q2媂}?P#ۼ2JulBQ= #nTAbv?'p[ɖd u&Zfܤ ]bb,DQi8!1VuYc_"!e""U-J}qw*pپD* B~AvaSc=(^Dwш|@v}#;H.ѨbT4PTh~DgC#sZQ5?{EgGQuvĨi:R];p:,=A0Ĝ?jf3Qn࿡Q3 d߽J΃EBUnL ͠tܚNB7 ꊁ75uPrV/!:Ū^bYJUo{;se?]`3h!5^ET}o}g/V5-ꊁ {WǺ=YجRȪƼn)޻\M70 {2©EExe<7j:\Y,AdF2EOwrԕ90DD+9du{1 ^!_iм(狥Ɔa}ٱ_? L4YO41sW&%t;~a' xZuX"&;.Kq4HҭelWv HF8w0+ =Wd'حfzVW0 L<?#)g<Ƨ5U}}8sU~I.~B5`LI?6YWߔI~|vѝ ihis-$?ͺm} uTQm4SxjG0 VochiV:~hJe)Y#q=]QȊN$~rn [\ `ɖj},oIN~[jRb(l6e9)1pX9XΗ8jHU5\]4՞jxF/=wˉ^ B |DdO R|mc\lx\J?Ճ,'$6r2OFیx&ݕ,Á>2៮d4]\fvߓ рPlg7yZNj"W!1:fföd#^, o }3ZrLpd*ʻײI/ɕUf;ݼyCZ4W =3dŞ~_NHmH̎mTjBx8_ûLdž'g<_~:4Xم;I=Ȗ~y3Uwx"Rҿyqv+G"=WjLa᪤pw@AWbv 'fORhn>#[V98'f~{κZŇ M{bl~5FWJ[89ͱ_ｗG ~5B Ab+ A!r .\ᅃ;.m yNw =o֍bCqW+O~_q,wc!&"?l+e~s)͋x;XM&85#S ɮGLɪ/>LjfM=FX+ٰvJ=7=`z8&] t}2~eV3q?- ɇY&Yw7=hwHñ(Q{ 0#wxAolÃTj>آZV6Zl=w/Veb6 c43Rys)^Cjϗ~y!jTftK?}9`s,xz#Fܛ:ͥ80pVjպ]V3 c-Y/E;Zzw.g 29toCvNO7ޔL]ź&k|>B5~p&p35 21^ 72`[+2\P NhȜ&MBRU{#L |Xy>fGC-})L :p[[*t%C2prfMToJ^P-~e,Sen1u`K髚Svpx"y+9R*/83k(%oYؔ80dߠmE*/qs)CkA5a2*`92ׄ3c'ZdS>^o(Kʅ;nT3=ZG2&<*o8{xpGt+'4ݠt+'s~+e^3AB~)Ue $sUz86m-ۮ{/L˸ `-Uaa=nCcgK 7\2=|N52SCnOx5J $-YII15hIj,gwn:c^h HId%"~.v>~U3dlI![RXI׹͌D= x[j5BMVYKUHp{mlVW>ST%d^f9U# GFÀtQb#Uf3S%2w1Ŝ 0ȗe2%9(ɼ-\iu:mv6"+b\NU)Is":vv > F$p6m\+}̎4pkZbu2oӛͦmUTM$K_t Uߵq wh6􈦇ܤsGX=!D> BZ.DlNmoZ 1N IHM2'xw贛 d!/TT|wGDZg.R"Qk ww+1hӾQ rUbnEwxЎ rogb d#]{j<]nF@NF\g*b<8e#?V0=jI̮8c7ȗ*tlcOqDUvCP-1QEb<6c=]Ez@'J,%b: 8L`;f,HD+7F 4[YJߺlq*j*QYM9=ڌdg|,m;}_R%ZE}@KsINMIjHW!솅m7r1Vf\, h$˜xЖ ^`OШ="Ơa7b(#UF۪%~4FYqA̭89j_rdj9ZSHW9w={GCg+"*Gп^ҁ@[@贛yPٶ^@.Tlu?N+잞i*"'/ n-e(lf3:rV<K[E|.3GZ)F81-Q Y+7%Jam,[zV]਋ B&Y*oaf\) " baf=ݞdwNʼ|$7V] ldJxzc#Ży>+8ngoDMz[Kex+B>#ABgc z0:BWU~zwawbXNH|SF.OUA?;ߍҗbH$q?3ý$,՚'wqniV/>st{#:㡮'#s5zRAٰ vjdb2 W-DXP%bEB~!y1>PUi #SwEMgn%z̷O9:g܈Wʼw-Dwe V%?!܎7|ϝT<?j鯠DPRNR(JeqSbr8԰_ulνuYAz=\Gs,o֘l;Ūjlkk2b ̇׳ee~~l=ZII%6 %W8>/ r%K E߯0v15v`*kTC~''}XK rqe">>C.LTV%R%^;V"ĸJEWy M7VYM(e{85'i'16Hpu͕sz^VfVb0ha7>,}M0`9)qk½* gog(N:'(TJKD6y N t]g9Ygn| D*2BTNP3q0;fv!6),mImJld>A#+K52>a7}Y}bl3}~*~ˎvp:AR2BQSFNFE]}Wb5Y'.$r ||UCS5+ޓ :B=**JRTk:STYQ5/s`5N 63.݌is[yl=6bS1 ==@#1 =@#1 =@#1 =@#1 =!3C%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00ŃDn|03dK4UleS>L7N[l<%Hk q"'kLͩ("^w2|OR#>.s0he4Dĵ$A1X6êCjԥ̖^f%gr.APc}E *7n՝4 >:9ŽahfK/c;3,6n7rq^pZpm:ҹ N=-^le67-a6këȦƓ~8tw:X)21$)U5ll;˫p\[ˇ'£TIg;F,ZSsI֋ 1|&FTC;E:-ӵu&g2AFgL(bJvWy8y.o&iS66ZLQ8c666TynCx. 3ͧ^#A ם`<u2dppܼoNoqE^y>K+cwgcPUc f-Lv\mE|\{H9$2%F>-⇃>췚32@8[z$B 2r6n+ͯP>l9e}(QK/JK7leaaNDo,acCx G;jߥ &v%lE+BNcOyVo`'Nuשּ=v4l|O'leVE&$lLJK=o7IU۱gt,l)@OlOΖ^bD[{ߓ4Rm8q>7ƛJe|:bf5qqu)Uҳ p^_k4ct,AfQ6FLm}^bH81ao,'j}a?gzbX]D_ՃD$,mf-J L&6ϵ?`d(~K>ȬW|:lCx]!$U5^͖al-g[84\s> YM7mw\?洞ף VJn-S(4[=ͷK.ߜlW'*mʖ}X\TTUZm;U5^H%se撬Xa/#gj5=4i0t̯6S[} ӱ6Ər,d޸yM|<`~epq:װg8 >'>g2.@WGECC.\۶9Ӊ$%. sEczx{VTB>ﾋ{<J6קS|}7dEfL%HfjɃV #MmǼvTmoel2Iv8~(BQ G5lǏqOkKxaƒrd)./mk#ᇄL CjԧOL%) sE 'o@2U>N16 dևCe=Og_۩Մ~`o/.C ى *4lj_LKG%uHUS:]^5lqQ6$KaI$jm?qbu)퐾Eptvq 䦧K%p a]wb1C٤F}ܚO -}!C@&2|r3EPuC]%ZHko'28w߾7NLvf,.\ ;ݺzFzNCUtm$| cѱжd[TvvTmʼn8نǭOSI7.`gT32VVbFFh1KZ  zDvbj{ ~ ޶6oǞ|mۿ[>#M{fr%Ȭ{8;F_?wm{Mbs~-n.x7pU %yV}_ƾuܪ8jA?rp8Man N n7s.^|u&y3/ %&U5Sv\ǩS1z6<n2z=.ekk#<8/؅qXOdhwOІC//]]hXh 8q+<s S\9N[Rw%6&kn|Gq"CpNNR]҇ 㭣rP3xp\壏>ѣIUT(Wbq%@(BPw}>h$6}$kL`O@}]TOh-z<$<8'T%jv<:z\NmB?L P?OF=[KL&^_|`_?r}(. _]_Yj-q<Z^>^UMOS5X|@d`8q3= #z{{裏CTh$9撬kC}!bD[c2i<6d+qz8 vC%'5?8|>}}zzv6X~$ZTc SPІfj4pwY[ů뤭OІG"`yO@wX~?T_R-y#tTs<8NN>;j"Xh 3c"A =hRk w_)cƒMp!6@~c^Û}#߶WfNLP|0'NZChǰ_W#V5,SsIJ0ۈUFt ~8tw:j%ͷ˫.oN]7DmXxXk[x4`OhhwnӓD'>#Xtu1 q jv^]/35d%jm}b8k @PuZpmOWi=gY9utivDmֿ{: a]>/HHwJ&_Ϫ/j3OVיKמb @c)fnA1Xo~hW+d|oo+n݄O¥nLvjj{ a]o 5 ˾}~Wwҙ`!?Trgii-ni_nhJ$ҵΎ q"w똹5ExZK>^K׿:~Oy=]v!o5[br.`sto)Ʀ xTb pG-|?s}aeG<} -~Y HIdJ\Ora)vT5dVy&fώ}w{I*6U> .C?uly"ΟmC:v߇sP!{OLF^׹3!=zq5QFҺʴMt#@""bHDDP 1B$""F(DD#@""bHDDP 1B$""F(DD#@""bHDDP 1B$""F(DD#@""bHDDP 1B$""F(DD#@""bHDDP 1B$""F(DD#@""bHDDP 1B$""F(DD#@""bHDDP 1B$""F(DDĈ@cz<6=ق7ӬQdLeOse2ggMElkؚPHt|8{7g6ٯ&?b r!ׇ3=qX'wv.!b/im5=:sl$w|w8gg7 Im9>L^q0}G->5sI }!. Yk} Ҟ wI\Jeu^VR~S[rwmz״?5=bxQC&H:dQ3莳 ZC*^Lq pb;Vs]L矓#x[~*ى ʉPFFvvw:`5W+Z]pfST6n;b߷=P+^!ɫW),/:sX](a}aO(u!캪ͽ M&)U.E8e](?k%gb.IP{PqV@ 73C54#G ~8fgv=wE~]Ufk>'Z=2R3ɮK8U+_">.=3:+rJ%R_~I j<BoE[o'mgY&=SE~`9Q`_`wXқAbs~>7[޹;EkӤ>`LmU32VVb/_&kzh"/5xt xAZrXzej.I\{/<տk*tt':: ݷvS.0;8';;:[NÍ[)nNS'249ҹ NZ{;f6=^0=|0h1p,cQmP u鯾m6^\MrGPz;FldC =}OxӴV.?kx(z"PJΞp nSNOSx}>KȶsZpm#j#{BdsvZ[s$^9$9`pl|Ksh8M7\. r$2%FR>֎}8`gT +p 6N VYc--N$SwʩT}N2 @WW|< :ڂ tljAd;3,6n7rq_@W).-mk#28/7= _sDc_p}*Ir>Q Ž>'AP CAk-T%s.̐vmi2#<69nT*j# *Z<.CQ#l|'ߵωG|\>` S˵Ƕv7GsDQKOkm}- twFهipi_0oBdP%!?LǏ9==tA&A:ܱqZw8,d^LQ.Wq`;kWl'P(,.}Sබh~nyD\u˝4Ϥ(Wjm}Gy 6=Y[gj.I:Wks|dm}]緭L& x9u|m}r2SkY>@sDvO9},j?2=1 XHqPϓzӧ@O/hSs托R(Uq{?ISqVOYMZ8}vR5Ͷ>ׯ?n8NNbkp?KHIe\Opw->zY/UYHnp0f䘄ݢj \gjO8Aay*N##TwakIڱVZ`xd}&XyPa[O$B%§O v45X~v >$PݺEuZOo˶|_X*R%.huQ[Ȟ#@""bHDDP 1B$""F(DD`|SЅ%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00G#tm~d P%WYj,f :٢fq84\;N ݆îT4 EQp-`)8t0uân&՚AS,XEЯiEĂ񐃠Gk+zl!u]2a+?ˎݶրaZRBN\'_c=.cN./.i>RMDXHUyTrLN8$u 8^utF*_%W-ԈMԅ"47IMxPbٕ XK<&pvyo5-AX#.P3a|.xA pԍ5ݙ/1pz=:|,պJjjpšQ/}^Zw6@ fUMZ*yzж~tb9Uf9U"2.?#qw5H~ŊQ 0CKoE@pt#~H>\/&siw: )/yX̭ 0dNS9vxp~)Dd>Y哛iJ!v7i[pw6ӡ_^.ej4a)-DXLx8Uxi#t,V >J;Ȏ6!% ܟͰ{;/i .raHpp/%F7,gy(vQ՗cT|)8 NFx]V'RLLu1>Z)DEDIu.sk*9V3+e~}1I4fHTuaqg&IP']nRKv4Mg3ܙ-qte0v7Gf ܛ0G7zגL'jۋ-slg eVѮ_v;c{/ ôpaoƻ:T p>U.3b|(H,+yޮ3JNΗwK/J̍I~|"ƞ :^dz 7Lq:pt;"nNCt?\M1^\N&J+;XnBB.+%D7-.Od+NtMK re,i-%|o~FW;aX||~eɺ n ~F{GDulLKu^4(KR*ձsLg P *:G4(O`YVL:RJ$xu_d(ʚR ~u)E'['_I58W.;%FU^joݜ5&sL'+aSNR/ݜo1/q~NIZfS9/癜/9_=})UWR߇)#\$qbo/f>Ukws`lήptWvJZKxϯPnN{hY/$ S -7a'[la[I*y>ֲ{8M鶶m>gv==<\p{}N0fWSF4ʉq>&U [MS+ J8 ؃[.ne4;#VNvlT3+e&8:.>Igql۳Ef- fXb#b2cph67[n>!rZ %v8s{&D KnكI$hK[rWW98&KI:ͮr`4o/%$}q^a$f0iv.Ϸ^-`br~cݕ,U"94dbh}Z*Oo䆻4{}|~+L:SUv @kIw{(2˙9dZ&?\Mw4,/nS3i:˔*&=2L݌EȴDgneٽ#%(kg?m,t>X,Q  |tJӯtN=rl#ƇC|ւ pjBPt_RE DT0Y0e"٦ 4=oǤ'ٞ },g$/4c/(9H-7])VLʌ}?f?ZsbD"۳b4L*Q7JM^SsmHo/F"*v>ݜe9^$-!wa ǫO۴MbթݔR_߇D Ǽ<\K[)>\, #KC 8y9g̦sg$sH^Zb^&7u [ǭumo B@MJnaY%*6avwkdBNI2-LS6Ušxvn GCD<<\i<lCr=CZ)Vt%R BNħqm8k/n*uLNd 8 ļmO+ ȔItA4ٰm4 ݰ͵faLcXM,?i{a}\\Fįۉzmhv MZ_T*V d:^E_K4jsKuS%*bNįi85NMI*_ѢNb 8 Ƽ"rp!C auAOBWK̮ qt4Pԅf_ߨS7,5-9w{ Sc@̷gB"!Ɓa; t\|}QcA_rUfs$Uv{81cGO k}f1pg6EMlgܴ0,C;|3`ԉݶQ-V8H#LT4΁ ;i"*5t_, >7RY?hOIצ|~;0#}͹nX\L~|22sk&f!]===͹g*_UyxpxKJ?^I>ƢMPYfy<ʾևAZ<84e99Re۽ ]a{džpjߜ ,!`0qBޭ :Ku;8+)V\0jgLOn93X<|t}[[nXrtpob0-O?9ǷN[Yd||.AOSZ̵y4t݆lQdž '[.>_?~0]4rB ˼4G#[.>ã>>̤[{3<^?r8*w;}Ho:u2A;[.>ސ*b}kr:l6|\1 0sYdZ+tK#h6+Ngҽ^w-ָ<ߝq 93ݐ=ΐɗ zڻ  s ^pf\wi*NOE<zClHɬ /p~_mNp+x\JUKwWd6"w?a9ߙ<+;}-qmã><25\o,!<>~F;3o k,"!.ek_π3TG:C|OP8h3ʽ3>Ya?GIJ^¥U.dw;G|Oxu<3gg11&ƃ>ZMU7{*lG TTG';kpSSqΦ)FA0_q1-ͩYwD;x(%y7W᫝5~Wv<>9f-(qu?=݃SxXܜZ3un;V9a݆ݦp!`1ҋ7%1t+KnO'mez9LGFP%NJ/wS{s z[LcW/s˺{]uۨ&3K[bf+E">{}#sjwOWk#[ N 7Kf vrςZي۩1s&ffYPZցP'vHd*pȤ 5juݓ KQlG YquG5q; -C?M;+^}5bf1-.M#85c.}=L/xcL>>uN2ݰXJ89}ebz9a'[\X*uސ-.%f҉/& PwqtBݰHf+]5=AQ+!YbύöOp U A,i`Y7)Wuvo죣>S/;mCa}O#XVYLtE,/LR)[ RդP籫C"S!uvYpUH+oq;T2*bx>RU@+Ox85Tq7|\ChJOw"!uSP`R72ų:ɗ F;EEKuv-@S҅$2Ef#NZ7I7yߩ :nЀntc):LN"RXb-Wk櫹:nlwDݔu TOU7\ 0-rF,fvlDxȍmgi!;*}aszu\vݺۡ6\ Oxm/3{zJ4 9^Ĵ *!4IT/~&J~ 31Wd0ncXLw.yLKpP"w76hB$ ,331۽rgl T>w | SpoĮo_pkfuå2A-0Lѵ+3Ff2Tպ\ף5Rn* >omxk wJx?ϮLCd8Ye-2'l rWq.utک&Bv3F8?ם *<{GL-WtٖYvuluͶi K/r*ön=vL36Y*\}#4p~D3P{-ζy&׹P7Σ:Σi7_L荨& u 0cSj*'Ӎ4ϴR,S FgCUfĻ)2qh\J) :PwWRd:8omȕT d \ S`\߯+I!x,wdo2Snw<3lxTrΞg;zL"!3:{`~u)sTl0κs(־N(rksIf7UՆl%*F "k(n"n5:gnyxU^;\| Dٿ;W* ?k?c>f>y3+MfxwcG,_Vw_I'THe"f?Ej]K]ڑa%nLx!T4[ci5`Zzz -gy~{eOT_ͤPRxMGMb9,8bhV|vQF[B􅛛RYɩ5bj 7v_CiX&2hޟ,x4`bJqta &L&1]e06Xg+2 wzYȨ^;Jέ"sEbAC{*/k&)+c>m8i .9]d!Ue`S.4iOȘ j+VLn5SD5vI7F%}ٰgṋo  ;3NW-~>7}a'Fg*iIt3ufV*d :q*Qe단 f=.FnbAO{U[ :|** #]58H2yG]- Ѹ_#מB@l)־bF$hct@!om,x`zAc%e; ;5B^;a~ݿ5fV*C*;F ʸvx+h7yLYKI|Q%WBBQ@i$ߣBoף ZZSXIXIj \ph vUZ]O ŌE SPXNjve|İM(Z i[%ULި%z1LմrZ#WɗXPTp,!0L@ȫBoӉ ?qx{*m >F]phl5aL/JQB{.``nie"~A_Bn(X-[mne߶DSW$v5,>؀v I-ش˽S5.{IfؘqC>/3 H:%6$U&SDA,EpTs/vwIadNFbߎڰ)g.H$-d>n*Tq `5$ x贫 KœH:|`ԵћZC1 1E;Ʀ8Iudac]mî2f5'tXɍi7~>z;-xeٴGnEz] J^tA.6kS61dI1`hf?hĒ66nL r綱r_$vtPѴX2a ddd".597дK6M񐓠I&u)$$w: 4h76lKn<zͦ p׍id H:bɍ7Dse9 J xGá_K[P=`m~nɉڷ4!,(zP4-hN"-mAIwԚo=e9%></7,,KI!l\eh2yG$좛}^z-ͪ#!3uyRB]膃+j sz_2T]\trz_i1ϣyO *s͉HZM:#9r"Z.@UU_0CFᘦkT쩒f`K2GrtH:SN ^qylYjwY2)RTҙkEn2:*T^10Mte=tF=n :ajA(\tqp$h|kͤ-ޑ0r&d=,&ցЖ{ ?9՚!#i/s7 ~zx=M[E><+*%$25|pÉMY:J?pqy͓teMv1S=G(8qjoOP:+u~r:N$i!l\0mtUȮޙ=ŸCqu#u#Kw2Ho3|]/'ܞ-[i; %v$p`8m*UzGPUM4˲qDZgۖ@l+ڒ  {B)IMP(y8sEo0;B]6NOITͥwJMWaY6NyN0ܳ=sn[wf7)r6rEgXxQt__L u4)H S=ɴߞٲa e .s~cTePw ܒ+w-^nǞk6/Pen#*PtB!pHû"-it|Jgu^;|ͅ NǢnR[xidnQlG(rnSW{8Xn^OZpvnr|IWmwB![tq宂0w$K.'H~dsYrUb2{̸ k&RAfpkȍ~NH"C} !TR3P(Ȩj6`<^rQ2{UƆL˻! %'s*q3!O) %&,eJݡ2gFK(-<80c߃ݶ)MR7,.yTan@v A6@^HYc.Yc1S%GTAcvos4TŒB* IbQ/b`E)-D pɗ :\A*Wx<.p:B[T E/bZ*b uCRU(UB*c/)vzN=A'ӽ )\3ur\YX1)A&(M,K`aa KAU,PQrp;<.;nMQ z4^;A]ntRI.,HJ$mD P"i#RIHڈDF%6"()@Ȕ!c1%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00Ǿ{F$ AB+!        垀 ($V1t<àhWNJO0AVN_QcsQZcgJnUّ$MN B\n2- = tr_5F- ap׿CLn@`r]m"Ԩ&'k1KDAEԈQa  /#4̽'(﹮P3g۳Mxj*Q'{h5ȯ I5;v઩j:b!C=5A%ձx- O0g\"J847c A!(cbyO~oL>.|?~L-=(w'`0gQKHRU[nl{Z7~_w2q7EmO?EBI|Qg$(j;yWq$ƤE0uLlF@}h5 mHM?H#rHPZ;kKq$nM6jBiTmߎJ) Qcs_aDR*{#0sFފtRq#-Y.Mr|(ơ/0SGE,-:?_2j}M^|F#q? Z-ւ垒G!'*OHpA d@"Ǐr&QW9+wߍ7Ep[(qgDBnLɸm6*Vxx3f :կtShXLx&$+{NxvbM#bh$xA$VZ)((vcX8q8X_PK,DL/Nz+h>L@նmt[la9rwk%2\˞Y329\rOIԩSٲe IIIc0Xpai;魀 H\YJXZn@$yt:YYY477iՑo{|`mj&/mX|]xStRپ};fs=Z'ml,li;ӧm't`EGhr2Fss垎p7|onuMOרEP ؙ3њL4?ag$Oy%::˱{`n"ېnׯ{`֮]7؊:tIܚ._2Ct4JjNP:{,oߺv356'kvv[O/DZi:+,9T\/._({vrh{!!!-"gn7 .dȐ![]u%>SFig(B\q=Ӷ.</sP]KOW:Vu"즛v$DO=z 鸖WpPHdxXbCt4Jv{:?}6m"*9}k<=]B}49#T/''lݺ.*A+Wh)1}en..Qﵝ;wd6nHJJJc;Yj7N9]r ={LJJJzt܀c IIDMr*=z 3PX?Qug3\dKKKcҥ̝; =64bTTܹsL>w} &t9D-GZJzG,7Uw^P OC aҥ=:NAl[~r*TTT0c h7O9sڞarOgA0FÊ+_5lֺ^fZ:u*?8/rlqy#_+AeѣG2e yyyݶEt$9\cUUX23yAOE3g$--{˱ɻ%~xN\mkƼyhVٳtXh<{VSQ… 1ͼ]t"h3ϐgfս(_^5k֠:ױ+=)T=]{գKXj(_gٲeڵ//Mnu؞._l/W^p71mXMXTd|rV^͛t\MNU]$tt*[oZ^ 'ڹ{߰a˖-#77Nǵt;`` z|gC='O駟qÇci+o؀ԃ<~i6mDzzz>͹sxwzt\Ԕ)pUUQcܧѯ?Yz5SsO/D:0L[ݻz=qf?|TŅ 6mo6<@ $'' PYYqx"'Not_YYvvd0tBf͚Ŝ9sXh"ﺋ45QqcPcc#?0=?|c;tv|"X'^uV+oF1LsI }}t裏2j(-[= {Nzlm63m-ލTS3$xbL&ncX =]OYhW^T"ƌi)o0_|brrr;+._uc,Xވ~ qq8ܾ]?OnW_}EHHzg.7[R|{t@tB _1st{a4z=#GhT9W'77N](kj(Ʀ{VeժU|'|7^g#t_׸z K)6mҥKټy3C tj;_-iH"`^''''xbygK龹YuӧOSOa222:ױkEv4ourGڎ܍\^wCQ&9nܧI8}t56'w^MzR(:> NzK=tR /.хסtoAERNp7!FG}Ć 9y$sT,cǎy}.,ؙ3޽rJvb[tBTeV}; 'њǛNt͹;1hNzK|,f$ 8aΡV;UF0it:gjYu4(t[zK`SR%00u}T*tkzn._)ĀLFL /5kNl~5W*[{ sg"` #n,jwʕ~{:9ߕt=#D&4%]w$Q~=<N׌;EEO^9˿;@GAc0P(':v7٢˯DELkjuu}NJuM 6)̼3N)=0spibG1fhxىKD$8{FN+Z.Tݔ$. FLf&/5r伕JQ&FFpːpKJ$ł><\#&IFBOnN*>)~͛uiF^ϔ)SzyoU;8V\MBቡJ =){̘(;*t%6vX^}U{9ΖK2ĢE\nW9rzM":mJ5c6?2hP?7&`v-[j*6oތbAl2/^ܧV8 Gk¨0bQfR|o|\.`JH};t+W$;;tq>#-ZĩSxw8]|\֮]ʕ+po;,^O bmlY@J|[HO C[G[QLT﫦N/\.gK~Q s3Z[jo-pEKkZf #FgŊDDg߉;Jl(h[aDRS`S\uuh LqRT֬YÇ~hdܹ߿{4;ܜsVj?o+X<ԌIƧ/8\Xmm-6l`ժU>|9s搕=k+X+iK -!f2S#RƎQP4FUK,aڴi yPA}% `ň0t~.X}j _W䐖*[Fs1"TǭfFz@98DMրOdggb z=c߾} 6oYiurm49m``S*"ƍضG(p(^>`ڵww˚&7'mPO]Řt*X?nǶ8DK}Y}YNw\ 229ѩ4+sCvbHnw z 5P_]7wZ_v nhMʹnLuKjp88xWG zq Xv\Rսis%R):`f/~% :!>TAq"//^xqf\hzb*(&`UN8Zl \pPXX۾71MHրuW;.HOO'22۱v;.E^^&Mj]l:Z)ec_︤yyy,Yī>~ 5+ xZ t~rijBIA0%츤`Ĉ+YYL|9Qby츤yyyjCk|fԁ42eR1 =rؿ?999ݎ<Dx(hN BMZF%3jX8q[ >ܫ/GY˅!:mz\#fmy% 0jy`t"w\R]v u%, U<"\_xjyFrI#cHM {r(((j!tXA/`V/L:x[_8x t;c㬮S|SzHdЫ4:uuj "`[o/KDQDA0LhZ,Y-1mfu`d2a2HKK㥗^vYUZ-F0U`$%%uu{iIƸ84z@5ɷ~K˝b!>9_05m *'0. w}= ct|$098eCADF<,)LSi) (DDD>)@o{:BSXApD}l0`)"`"` !\8**@ (D^Z O zQ}DL!,E#)Ç0G0yvfg㮭Q$!05=z\6 hLk t;P ' YXƌ$q>D#I$$!PKDA#0A#0A#0A#0A#0A#0A#0A#0A*?H%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00|lV_<9GPUUECCCC#oJmF FфUCCC#hªg4a3jhhhMX5444&yFV ͌ne7b1 D4!Md$2D". &:mך52T$3fNn݌ni3 %MĒ"H(UBG%vj]~MXYVLqzӌ^Wx+L`4M b:F`IV ֲT,ZaU4}qΌpM4xm4l8dP`0Ev=6y!h\L<%sj,QZ+;u+ ZĒS$$t5X.:a %$92j6Tc֎TLRLStYYԹ'xOC}VkyLZ26d"#Y`]".a=7aBv\8lƦ cd,.sqM*^ HZT8t.[bM:]41+3͕XRbax*AKm6(TʲʱCs*<\ELSpiky"xLcqV:[lW.M91ĭk+>bUUbi[KL^ 4{|hc T_=?eMW ZAȊʙ0;x,I"5yDE`ڊJ/wdEHQ[QjʒC1v bYge\ "H}" e@$q`D5w XRȹz{s-5ˢ8a=x.cazlrUU&DΥk*G<}``B暥Y&1LCg`zљLF#:ɠ"(" R0@C+RCrS'U(FXaW#NP\f}OUU93fh2ݛXڴ8/d_ʮE 0>l]]:;oXN&I"903 -YMvI/1ۧqkS+BXGg=5.U®A%X8Ma>+qY J=zɓ(͝{rZ5`6ěg-9W孳Q8cŕ/X^ -q^]jkkzzy55N4%̖kFRI:FUa5+œHڜrf7w޴ cMMM)8fV%yGcE}~фu2#!4`/NOEбPԦAemRRtc#w`!v4u2;*¥E2]h\ksj<ɑDlsv25KuUNnaĔu&57݈+צH(}6jňѠcCO|+@4Yxk(! /\wh1a]ԦGo/z1Ik6@/gTYvt0DDdegu4.afi'OS̳~ aI{2w64m[1˪&B"}ÅTXC BlX^`I O}'È@wKuTŶtiM)իE"3_VC_9TX{#= Xb?r88p:5o]_S1\֖ڌ"t8Wb?n3oNÃQ)n ,m>GU7Y]T%/@"QUs}tƕ "Ɍ̮!-:j\Ē&i8x6J& M #g175kFӁ? YZη$3(t(@KC h\ ڥ5:.Nd sMwݢ &p,[b[ 0{2ήȻ"iz iT8.Z~´q,ik{{(lCTA]X_xkemE/+:|M0FT(*vtY cmmM)--ױËϫUo\Kc :xy(E2^8dEbKmFY!SE EXU ӱZA0)3up2I8)RuB5aχ>~K|y=GCyZ"z<;N`yW}ǣ,khawɤY,Y,^":)֚a2B"=ZLEE2ZS#LZљLtJW;o,3)biF} ].^?i'"t6iyTIDg^\g`6#H֦Z;є7R,٭-4LgI9-H.꣫BPU_ʋt:LsAA&YQ k<%34N0X8FZGs(qt0Fk TUJmF١"/"iw00"YXYcC1jm>[#ջx܅sq jD0fEDQDξܭZ&ւ8ڤ#^^`h*uk&Sqhċ0P2kW)=Vrx_y L U8I_ZjC#1P.pWHveg +,hkz|$AޢQZO!˗֖esMˇ_ jA W?8TkHrϙ*MҬMj`1qLO^~b'q;XLR[(.viD@}uamwpb$1Xљuq׻(Mv\~o8As;}9TOoTeSS(^uӣ)j4oUp4O]cP >m^׀ ' Ո (*3jl_8`^zn2AVJXMz,=7"v^ \ p-)CC(͝sg6rX2Kyݺ5;{g1H%_`E5Waȹ&dDdeW Ax!IDJ@*L&3uՠ:ntsUH<0 ףw. Q>2{8,&4=-s?Cj9$qV^N?Ҟ^>?΃9qopQ~^$O=#jj =I6+q  oP24_C>q?%Z?sO=z^X/'-6n΁x#_⚍ۮ8FI"UUU1WP BBXSZۍnGg2!FEPE9FEp)$=vJ,ZߌЁ؁Rxy5[{xyR%EeŝtMLE9}&'aJtjk8~-$qF};~/_va2zv M/ܖ33S%=г_G#]۟oxU<#3 JEd8KD1c_։mjkt6_PK{?WD8Ao>O6F\Avj745בxv=I<ݞq9L-P( UHUoSm0oYa GE~?ء7ry^Tzn[d2if _|Mn{04w_TXDQa-M:YǶ|9oHdىfŎ#dtdEZv 3Tq-L?mr"3;_"}G2vT*(sF, %6v056V?|&c/M:"rjLL?MfTUEd0-C BdtY|梟<}%lV*-e汪*Co۲#9Kvz7\Ofl[I>0dW^j"/';Gॗm /#ۼ!7GRm zߜ#,V歖=;Ebt /&Ae0MHT*h[;&g_=}W.,)PʨT~4惻0:ln %6 sK --H0f7z6 Ff۝Ğgm{zJmjA:Drr]{ZMF"윅u>r8jC$طֶ.t,wVȯ~(:Q>"lX4}^&޺[9ˌ]t7A2WO=:q,,-\B3Gp|e#PםC0_#2a_!61d&&CƏ>sbseO&$c-1Co~pp^~9ƽ|2xmlVjӿ'3e{_[;?M2e|׿̟|!ź [I%yp(ߏ\6HR b<7lق{'f)9{~ӿzEO~J>[5)XR(珑vŬsf1N̽l.cqiy%a|tH4" a4vۍM-\C~kzLONOy`4;9^~@<eٽs]k?O`01LH&|I^+q.[;N^|qΝ>cZڻ:vNHvoI!cؤM} n p0z<bom"8W*zL88cc2ko@Z'Y)s E :?zO[:F xnݸ͈\M b~׬wTnzdՉ,߇XK@6f'?%ӽiւgO"tv AN0Xa)d\;?%{ ٞ d !E:}Oj[Wd&'I=և"+dFP*oªt(^V=.ѳ3 ҽ|k6l~뮽䵪fդ(X^X1O?4?0/Lo]#4|^((5vHlG&3tCbs{;F^/ ^eK,R0xTֻPZ62}sJ-'RtG#j+ɝoL_qvaŐ+Gy~:tIXv-?K^oxv_wR}*ԁԁ(i0i DóFl AS4DL/Rmj2 deεF>?=9eyέOP[_(Qn`ffOkH\ $ΜE:҆.yjw!wl$9٬ly6+%`!0gjғȥGYE(|Ӣ٬xɨñzuV4|^{;^*zxC($c͡CVQDj/wzskT*w "5k0+0Y<9 :f= -ΪQd)zzDj%}8׮)p ?\8Q}^'@Yx*lCyJ׻MDbǩȈ%&&By,S8V*p ?o^z` `p1ա/B4)ͭkNZ6kªQTR,V &~|sCC*wq8tr7qzOngs&jHB^lc"=a,p ?̷*utzQ24x_B064F0cuf܅YwE1KapFtREU!IR[Pêb-hgVC#±4mu5k1rNB"+XGyݻwUTс?TꯡR"yV4XĊFc*Xf{˰ Sm`t#,"N={Q:1Lk((Hܫ, V< M MSQa"C8@R_'Chbkwɰg(傪t(Œ"faάF.LRt7[/&3ĜgE<3<{G0hџ] B4.l_,MV&R[IY2,͗HnFCo~twwoӦM|K_bxx5_Wx'x_~!(ɳ T0Ewu^];8`EcרRg,i]rIӱъ?ʽ慬o ?CCC|wwtww;-F!=C%ټ|~%dE!pڴg"5/ļ+}ѫ +Θ[r|1L|S:7r-5krg8& ޽{D"lܸKN$߿h4J[[6l `*b lقt&T} EMVVg{JhTi1K4)ueXw_!-Xԋ(+"#1oΗeR[ZZwN$t:ͣ>w}>?$I122mO`UmޟW`E@רBFg4.w ,m1>se y g]I}Q~w~ߏnk_9r|@ O<0CCCX,o|: ![}:H1cm >gi&Fu2WlZeoX|püyN$I*YL(bqG}4M;9دϽS>Q3TCib؅@*LR|l,H mf=VF>4)I&a]`b& $`ʕpVq VՊzA({QqȦM.yK]oXTIBIP2ʍ`eM UC(forr(T/G2u.h+6v#Sof>`ì:`孊gFXP#Ձ^PW9*gܼz}nZHX#59UVf,@Ӛo(x9524XyTi V|.#RڐP sH m(M[|*gܸ&ba14Y]G4 U8;ԷH}yɂ򐙘(xEH$#&=4T:X RHIּ+sb 6;u՚uiqz˜AjtEEᡇ⩧"8%G QTP[Y* sAϻ6x,mqfXҸ<фT$+KmƼ 2Lܸ0-{ "6[Nl=",p'v/qa1 u;V;^qVJHԦ UU9znۮ)̋ $;xlz΍E iTtai:w_[0LijbGe*cǐ2+ڝvYBW]j87%"CUi: _óebr'N5##=2RVB1R2/ QP{Am3^>==gGØMSgn]lPϯWU$P_CMYQy4wlD}NZ&TgqeGwK]QO@ |ts=""٥kgd?KUUTNfud^럡̪%HrUiT'bV)>8ޏf>BR@\PVUUL___u*8uބRFcذs(j1 \[QUXfcEkfU+NO]XNb_T_VL`+ko()9M up+ڶ^-xyYT֢pNᦵ?s:pڟ@pX 9YeIM IVxZSNE͗XdiXƕ31ޭ m.:Ƿ12cӅ79t( GT(7^jSrBUTbyrP~fggh"9>S;qXKAR8sW }c2%|9>E!ÇIBڔ83&J>3tܿaAVbHe~-xl(6=MVn\eHeB_3޽H$ݻ:%ص̎{AW>1160Kݠd/77qn$%ihTIfq?:YY;wao37ߺjYo|LMv"E|k_+0 *Ix[PIQc3 Ύ% AKB gn?h-%AdcU3ra}gv,KtZ Bttt//hmm-GUx X\wW3͍y;JU[1sFflZ;@PEGhVܸڋoU7}^Knf??СC?NQf^xt"Cf6eΌM;7K/P?㧻CGc/#5fIejVΒR;&o/=@ѯ*[lh,|R|"Α08;3; Rz>b"?=Ig%-PD"od ."{vmIO^ N赽D%uP-;;ft:gnl(^Y +@,%+X-f-Et$ܾGoZ &~ny܏Y+Η }}±s3D>ժr #)<,`14POl|STgЛCf=(uͥ6Ȋ$Fo+*BXasxc +p٪{Z( $\KG}uSdc˪1z JJ`]UMpV]ͮJXT$xgfw&tIfd^;LٷhLQ{-{zz)-NO3%hQJmUQU87,-x+8a$~cvi-. YQ95bt:m| ], 8G|mñjUY ܻ(bV+6VDhBlfwo)ԹR.oGs$Lkԕd0I@3wlfMBOPih SX2q<7X 4aUQH y )-dC58ee3aFqn\2ߠ-0{C2Z_] 8> rK+Mpn"4z](YODqTLZSod*ɡ VnƋR_W]F{"G&#ʜ 11dJ4>Ȋ?gG6|aƏGg̍y dQCC$H dzvFuVNt$ũ&=|hc - U#0>>ce^|.M`?(ɜ-2<ڲ?O$2Ypt8NGV,3CC0yjk0yvt&ɄhDQ$ %AIQ% )""dPU M%0ۺpIٱê*;]U.pl(+BX-&[ywV04uʨU5Kfy/$m N]X3Ah]$>BȤ d F0QMf0dW ˋ]⼘ 87&#Jln/S *]dEH}'HYnu\kGȖxcfB)-qi cXB4QhZlvqTrwȊL(lqQa3O( uv]U%eFcȪn7뻝TI`F168is`,""GJ\cakE#IJq\YGS2‘P d EWKt)rQ08Ci{UJf$%kt]YB]TNrf;kEyфd(d(N")jeU:ˢ}/Za}?28XsYEcsYQN]VV2"if"Ib,m5f5XbǡmFU$t3INM$mԸx沪ILg Dӄ)B)% 6zZlt֛r3*W4aHD4)T@ӂne3ᴙ"RV!&$ DH}`iip!BPaUA.a{n|zzzTuBBPBH%B*˅\.WuBBPB!B!eWu딑۷oC*CѩвeK諭%b˛6m b`ggX !Bq(&n1c<==0i$\pvܸqݦW^W(`t͚5SZvڪbӧOa``333U]bQQQx-{ebbZj055C!B JIzM[nbXrdee˃T*^uiiieٲe\ L\.Gvv6 t޾}>033õk>~~> 8 //FFF=ƛ7o>>''|`A*ǡCP(Я_?vڵk1rN<`):w ++rʕ+ ǏѨQ#l۶6m:uÇ>9rݻw@ (2 ĵkr1`kqFhiiaŊ_\.GƍѻwoٳDcӦM?RӧOCCCv<޽{t 7T  8;w,B!&jӦM9r$L=eP&aڴi@-G.\WСCSSS̙3]߱cG!##fffp8p8p`̙2ٳg+7|Y SSS̝;]ヿ}kD"T*ɓaaaf͚͍MV[rLL b}6m^z^z(-,,ȑ#aii `JiФItؑ6k֬:w ;;;=z]WPPnݺyl M*DXÑ.[f 222J' KKK G7uTر={'O+>?L]r9u_~ZB&M0i$|\x8u/^\}믿ݻJϟDR5꓃v :u .,B!Pr |t?>|/_BSSNBΝ 6l؀{bΝ ;MSSS6qp8HJJ*ւ?APaÆ طovŶM6De˗/Ǐ ;v :u‹/=dDDD(jܨXd ]vh۶-`ҥDll,p۷ӸqBBB1bmCPT:~A<~B6mТE СCDxx8ׯ_{"<<NNN_tyXj6n.\@FFڵkW{;F :t(ڶm OOO"44fff_,Ço}+ \rhKx P/** o߆:|}}](,,͛74oޜ]ddd֭[,www3a\v qqq_>6m믿"11\E۷8s |>vtqe555?zzz8wuP.oOF֭={RBkgggxxx(hҤ qyHRt zzz Û7o[ܼynhkkٳgHNNDb{ACC:uRg]PիHHH 5j7op5ã\B!ZI.믿0{lhjjuڵk̙36zb-abbrwhӦ %>_9s8|www˗/1o<ܼyjjjpuuUچƆy$}Ϟ=Xp!eQn]EׯԂ~:7o5jH̟?7BRAYɓ'  ..غxbG۶m믿~X7FVp1qv}bb"|}}[lA߾}ѷo_<}fB߾}K{sNܹ&Lە3 aaa~:\]]h\GGGܹ/^AZyw؁?r{aEڶm?~<&M~L0M,22;wƵkװtRtڕ]#8::bx9  6qaJ… ѥK\~K.E=zӧgΜAΝlnׯ˗/1j(̘1hܸ1?cǎ!%%@g»]vVsmvرcE-Æ CnS\t 6D^^[h7˗1bRQDD5j`DGGcʔ)+BQ5j&vڈbvkժU554csׯ'O`׮]Xb=z1c`ʕlhmmmERSS?9w}/033Ö-[Çl!ذ}jݻwcٲe ¸q㾨Lw駟0n8}o?~x<{{RUp8;w.j׮I&wȐ!2d?qU<~}P>HjР{F֭h"p\]yyy믿믿Yx1ի& ,@ gggDGGr 5DZZLLL333 ((`///̟?Æ ða3\xHII)RRR`bb#!!^-N>4lؐ}2|8::b̘1J׵h"\v둞}/}ȑluѣžyf#44`Ν;M6e+͛3vvvx"\\\zjRҰsOŰ2Ҁ%RQBMU^O?aĉ엫B0 H ݻlID"App0fΜYhjj- I$)%JyEX_H$Rz8fϞٳg%}g㳱Ahh(۪/hР/* ''O477ǜ9s0g$$$+sK=f͚F*VJ>OP`ڴippp[ׯ_666hԨ_xMK֖}࣫ www<~D ?C Q*~5555ddd`ӦM D^^򐝝]kpܔQD" )%+W/\Ç+… h۶㳳C~gxxxcǎB=Nxv6 >]h 6҈ 5J ! %Ԥ\5 ǎCv0qD`Ĉ5j,Y^zA[[666_.)///,\cƌA~~>lllʥn֭yf 33'OT*\t) XYY! -Z`7j ӧO+51c ѭ[7ԩSׯ_H$Rbv4i̙555D"JEDD ==C\\|>{~ڵE6m'N`ƍ2e A׮]acck׮AKKGٳvZ(rIj===L4 k֬Qa1wU*-mX,V* ? SNP(P(06 *ڶm~^ݻJ}aa,]Wr_iq\{?vvvhժRp@m۶!Ci?lԵm۶:SSS~z AAAصkfPh?K?3P4VHHH`,5yyyaÆ >p8AHH&Obbb`mm ggg8;;c„ BLL ֭[4Ґd&P) y6COkB!F 5)wF1b׻~tM22ZqtСز~N@Pl}t*)55O/Я_?9gkk~gĉXnRksꪩ߿?*Bڵ1w\C.UVr6&NԺO? =z􀝝vBCC555>}M^ !C ..o޼GׯCpqqrbf.]xb?SL)6އ=o߆ z聼<\t gϞ#t~HOOGvv3f z^z!55=z􀏏,Y]e˖AZZp-v퐐xxxsΐd}68PK.Xd ?4斪$455ѦMݻk׮UZ|rt[7RRRcܼy->[Jsqɓq]{իWqebժUܹ3ڴi///yO>p}vR0 _XXZZe˖Jz޽ϟJcbbC$cǎ]QQQxJ-o߆;c`` )t[nQFJHJJhe۷ccctA߿NNN[hѢE)"##PXXooo{0 n߾/_^^^J񥦦ƍCzвeKT{@\ irHe ,) 7 * !|E(&D usܿRuEnݔLz$%%aժU>X9nSgφB`w'ҿ Ħ.[1K0B2TM>A*JT]^^^RuJZgffcʕB*: h`%@~!t"⥸Y p >TN!5 %LLLˏx1;?VZX`VX\___UMc͚5*GCȁJħFQpamć!j| ')Ojٲ%.\0H5t…466… q>}ZaWwU#K5yiؙYMacGB1^$IQ u򵢄|R.]gϪ:R={111TGchh ڵk8qKïPTu(2xؘM}!z5Ӏi9 ,P1SrM!_ŋ:Ru|c׮]tuu?7LR/^={??R}UWWGfͰg}NNN rqQhѢ(؄q1ԪU 5sr9VF|Է@KAJ!1JA,|DjTN!MJD,̙3wT,,,мystҥؔ;%+V}U%;a{n!R}V3p*ijgp%")) B!100;zUeU > 2D&jBH 888`Ȑ!B*\{s]3׵145!TUPB|N::t(8\C! ĥ.GfƎKbBj<H̔#.M 9t52ʈ-%ׄR(&_ȑ#ǔ)ST B""" ¢܎+HO?ASS&LB`7YEerq`eȇYI!jEf̘ѣGQա*˸w,XPǕJX~=&MF!ʲp###C222-KKKUSRK/jr9\׆45!+J2doN}I1=z4vUǖdذa`ʔ)\REdeeaѢEͩKKKCHH> Ըws]!W0X* '/C2L drl>ST*U*ȑ#СCaiiIt gdd:s8t萪QC-.VCtA$ 0ZqE!3PP ! } TK<'OH$ºu HTѡCUA֭[իWJZNuWO8|/w" &L( !Rmq\L0QXXꐈeeeTa*FOOrh!=aCT GfRdȨB>jB>b޽ Su&00qyUSf\.ƍ֬YXꐈ ) r!UF&R㠮)"|DVF|ĥpa,XB5!%ԤR U4W|֡ !55C*U:uPNh׮8tp!۷믿;w cccE}(݋7oޠnݺ0`ҴJGEnCі}6m5jo>mڴQZ|Ç!0rHXXX`Xn;`eeywޅ9rssqB 6 j*=Ğ={ {{{ߟ-} #aΝnݺGNNR)w}}}U}>`ذaؽ{7V\ ???hii:,dg_[XX|UHR$$$|>$`hhXGIrs}yhZH͖#6MabX3׵%ׄjRٳ111dڵ+Μ9{"44HII0x5(kMCvгgOԩS8tN<ɞcx ~7G|:==111J{꥔P߽{=zI`nn'GXd ̙3~ {fcKMMӧOѵkWv[}}}4oW^#v܉$d2t'OġCѣݿo9cǎl 77쵾HIIaNuA{Ȑ!ػw/V\sB[[[!*رchkke˖%,55Çܹs>/IIXXD"&%%w- BW! 0LڵiӦM&Mbz( a&77xLll,Mff&)(((~}P(WWWÇ2;;;]vL^^'c3f rJe͛7g~uRR#hv +SF$;ϠAE1 0cǎetINNfaO>̊+ёyvÆ c?xD_ `nܸQ.*0gfU\Lrpp`1 .dȘ0[kbb„Yz5ckk 6=zcccsVZ $$ƨ[ұ`ee, &&&J4m;v(D"AJJ ,--ex˗#44vvv1c`(6JJJ.\X +f&ÓX)n=+VF|pBW>Hm)S`ǎʬ@MMp8 ŒbGKKK)_2 4lذ\f̘t<@ǎ0 -Z߲ [ƲeːQ'Ջ%3g`gg.ѱ|8BBB=[.֬Y^zsl:Pnh߾=,XܺuD=y͛7WZpB_\Sжm[6ѣGرcP(Ŷͅ7;V.'U4:uxx(ő;Rdi|\BHE 5vb={666fbƍ˗/#%%Dx<ŋSem۶ B۷/={L!Q.1 B7;wƲeqKoEl2WIK0`:Ǐijg.=Ⱥ~:?ѣWgƺuyfܹsjjj8uZhT 4 !44cWPPW^!((n¸q믿*S,Yy|SEnݺ.p+''ӧMV!7cq>7x%AXodHΒ#;_A=3>\溶0!6McޛZJBHB%ߤRc֭Enn.lmm~@Nжm[cڵ+Νׯ_-Z@ZZx<Ν;~ݻ7ajj(=ză^-[  LLL'Nzd\''' ֭[={b…3f {)))PWWǩS> }hӦ |rt]۶mQN%e(]F'dРAD _r ֭-[ێ?=z֭[KtYfah׮R)߯4`~~>;HH$D"Avv6pe888(";͛bz-E8NJw<ʂ0iҤ Ó}?KHH((d&[2`B.48r8PBSTSqj|N->dr 1St9^IɅaQi5!jTw_!,^X333eSN3ԫW_#33ᰴDڵq>ʕ+:^W^!++ ŒXwqQ"33NNNJXB~@xx8;m6^zUC555@DDaeeUlk~2z}zJ ˗/۱pBL2 ˗c޼y|~_AA455iii!??۷/-Z/_"$$ZRz͞=cƌIpUt;훶6 >z>>_,mР~J6668wҲ/^@OOO_1cM6ҥK4Eq>-% E) HK3l&B.4˄JK6CM!,Z",u^= +b1Μ9w!1:磞= pꡄT*}}Og{u=OV>ݗ144 kk^ׇvD|ݻϩUV$BǏױtR 2䓱7oooxNM6!** ӧOWZ9rXd ܔ?uT.\@ӦMBBrDDD|P(d"ݺuüy:uoߎ={*Pahٲ%zչV ؖBtf 3Pr%%J-h Pr;5)9rĥqFEs]Tѹ߼yadfv|3?=xr trL:NNN|%Ԅh׮acСV >+V`޼yJN'''7^^^0a}v?ضðaÐ)SFWWWhhho!??GAv퐙P|7S\\\0rHxyyGll,v؁/իWׯpYfaȐ!)VnXp!<==1bDGG͛MkԨy8q" ˗/K7.1E-݅EEw^ IE\jj^ty\iu}Y! kC>x0֩s]b\m䛊 _7ƭo6`…%j![xbUA#GW^TQ{M6xN8 ?]6tuuyfBWWJTIpwwx)i&Qر#;哫ZCnݔC+ \pCvv61cƠk׮U|}}aoop`ӦMJ2666hܸ1ۅCKK ``hР+[8z쉬,H$}Ҷ(((@RR܊___#99֭[YfxիM6)_`aa777e˖PSSq+ =M.uZ^Ň.jŇ>z\ 8ʁ|d*Ex)B^I2E493H{@VbSqn !z<8 `Cn!x)JSWTz_!C݉'/eоk_U*30B lBO057 ۷zP-6lv]]Tz {k.̙3X{R 8{UuJ"""퍧O*=>fΜ4\.O/P*7JaZ/5g0wyusok+f&C|zhumVs]O1m'Sfg5fHC%䋘"22ΪT1111Z>]؆ CVʃ͛a՘5k'Raaa0am۶bU\\x{d"4E.o--/*+g'GB\(O~G%R'K $ eLB`eȃ!¯'5%V6+,UA>jE:v]vaѢEF%5Wnn.n[RXb,Z'O4i.5k`̙,%sNԪUskjjѣG{.^| }}}L8F'_Dρ]OoWXԲ/M<_RT? Vզ*ZzfHd IK 6ҐW!#r+ \0gPBMݻ3WdHS(HNNFXXN===$''xzݿqYL <woFMУYŽfΘj=bM@-Ԅ*M$aҤI|2~ 6Liꡊ䄩Sb0a\\\T}H -P%ܜJ}k(BD\rXtCx\@KąۉlkguI%pZzz~X޻cwbT?h||ZиBjRQBM:tza+ӧOO?qMշ.]#GݱtR*&D6 Ta'E*PP3/eET}:Eɳ-@l $(24,C.Oes]3 Ư{N ?/;n@bk#*2N9Qlά5vLe2\ߕ΢gi7@ #=ێ6cU%jjBHQvm\۶mŋ1y -ǬY?bԨQP- %G|Ÿ%BP(ٝW \iYQۯ[ā NjKM#9EɵauP(=}pg,`up_#a5Z:"= Ko\&Á] Rwm`4/-gscɸt~ >͚U\fϞkBPI&v.B!G((oӇ2/Th586B\ (FH:\X+z\.IC{cy7Ԕ]iy/@Fz*g4N.XۉKgc'C^4O+iK1^DbƘAq:GaB}6|8?o=&G]ٮ:S:zhԬn_n!#=ϟ7ky|4n \0mT>y u>{h@JrY)hٶϘgOB.|;(沲h"xxxϏ JKKCHH/_^zy{{nݺ(_1i3gV^ \^} !TvKe +Js \x RHΔ{ uњM8}dvl a0pxp?0U` Jt{so8w|  MB[G#&֡kl;¡+޸Nx=oƱA ww =`faϡO( :cϡ[A}"Zߎkz;7.(Cރ/a֟?yz[ָ9n]TsRQB]9r4-СCXXX ,lmmrJo0eTȹj׮srZ"RgG%M)3 ZdYrp 9.#E>н ܸ|kDvf&Z7IXIFo\eR&\qit=/]=!?!7-l ?/H2`6n*v3tW`[bŐɤu"<})vmYϞ_\PKz gwR#QB]c\4T-G^c,X 2e .^EaȑVmeecʕhӦd!Dưr?r?-0kraag9jQ*g óD)t4P0@}+NzU v脜 ޳[Ƶ}"~uLs a䌝Ǯ|t8~`7MLӶ}캤X=>;{rz]}dB"),VNvXß3Xy< #Ss#-,\] /v%';eQNCS1_[#_# 沲`jj0)o+|>>>3g9[1|>|W^#qyI מq&܎,$)28FoWu F5ՀOCZ9fzfXɅ(Pό9nS/ŋ0@~^_<'F@[:oN@SKTƳ#Rph첄HINd_s :M*6IJPS1TB vc]D\<}T)cවՈ ~gظz BK['CSʸ'AbkBga!9wčKg./T;B]) xUcnDB' +,w%[nŋ1ey̔Z+:Iوb9sCBB!2J$<[B/x'.\DK#R=ikkPaT9_[rY$e% f dr !q'Vu>oǃ\&Zk B67^~j ϟ/yZnEá(ӧJp8_}h߾}__yHOO?UVZ_K,ɓaddTn j*d2 8P՗LPk pڇSZM1RHd \k `mT+DZdU\ljjؗ#_̴: ȣqwwǹs q4k֌][[[J @޾}[lXa̞=ppp;={=zT,I5klX~=̙sss8::bǎ`k_|3g_~aLLLn:EĻŠgeeܹsxLLLp-$''ٳX,fwҐTT q$''ӈǣGG[ի˃֯_ϮƍW^͛سg@__bקP(#lٲ7oD^^aÆnr9|}}ѪU+"66Xb{\hhh =?7>ıcǠW^x9F1cư~0 ~wܼy ظqߏsΘ9s&OٳGȗ¼y 5ee$2Yy $d"I nGbcy!1R$d!3LVB|T}[jK#uo BӺB4Ƅ]WQ]Z \{*ƭgbؘC6&||N%ӵ4\^^^hK|2RC73R0 $كx4e仆)((ѣcp8R8P(/н{w={n055Roffooo@[[x-444>?0ؼy3tttݺu#FT*Ń---_dزe ]v۷K7[_P49sl2EU[new<`-Z6l(uVB_ڂ3fs<խ[J5440oFT~p\' PʓRl-@['}9 \}"F}Kdr #WoWJpM6ŋp IN.[H͢o`FXt)T JkΝ;cȑX|y?)DU +++DGGaO&. wwwC*~)igrr2b1,Y׷<~~~1c;֭[8.bԨQڵ+:iӦgϞh׮] ]V9s&Μ9 b̘1pw/*H???]۶mѣ)&֭[( hiia֬Y8qbN8rM===ꊽ{ۥNb1~g\x|>z¸q;k,>|@=z̙3ik(>;w.Ǝ {%G} <"9K'KZ:?;gtfpUDKM|^~pt~ԄP@B׮]][O+Zߺukb:u ݻwgK$bx5O>EVVV\P(믿zӰŋDl}e155ŤI+8pgΜA>}мy*`v(+_$aXnlقc҈Uܕ+W?#((VVVx9/(br?3޽{xy9s&m6dggcذalbQFaܹsܹsp88{,lقǏϞ=?-OI r8ZЬ|q3M !?+j"|%5TÆ UB1NNNǺuЦMٳl hjjbƍ:t(VX'''?ģG>P(D"7'N`׮]JyyxvɾDׯѦMK,1_333tرD>w-ZMB(͛7o0j( 8jBll,ڵkW1Cxx8ߏSNpuuNݺurJXl&MvoB3gO?M6a„ TWaQQQK.e۷/^d_w}a_>|FFFHMM3f(Yq5(((%V9s('O`HHH~6ހה)SptèS^ ///DEEƆѱ9555>|۶mٳBCѣHIIAݺul2pdԯ_=~HH֮]DԫW?g(oԺ\}KJ&CPERw" AMA=M&|%5eassstҥض|>Æ [aذaJeuUؖvڱ}}}hiiȑ#ذa^)SSNlɴۂݾ}{vK kkkl޼#;9(ڵji&0 xESSSðaÔ bT2X~:::ׯ/[n?X͛w|%e:t}vE-Q݃>QHϟ uh׮Baׯ_BJtR<|w.uJKKK-_`Ǝ 77/>f̘# &M2eDYݱl2b޼yhӦM uV*%ԁ8~8v+Vŋݻ70 4.\)wnݺYPPvףiӦ8{,ڷo'O@]]Úh~xZZZ͛7兞={bժUҥ ͛VZdXr%Μ9^z!)) jjj Ĺs0~xXYYaݺuׯnܸx!݋%Kǟ ooo<xz聀xxxĉǏ) j] IFE %=ť mVBHl`GτbH6`U@W2]t)̌ TIL%yrڵkĉ~WIL4ٻw/#RJ,̜9s}}}q?ݬY9s(-cLWW ea~W캍72&M*vUV;0LϞ=+-ҥ sԩb>dbcceÆ c/_݄ bHMMefΜ2͚5cov݌31cư ;jj*si0 0̴iӘٳg+mgkk˜9saڵ+yf>>>K{|?cc.0WD .c2sLTE'P`_21^2^2G1rF&gLhL/RP- !_ bǎ~:Ο?CE6VErh׮~'cغu+TrJaٲec|L:<?s#CϞ=gϞx]]]ڐH$f͚ۈA^^?^*gϞaǎh߾=풓ѽ{wlڴ-dvZšK.˗/?x}Gb1.\VZǝ;w0R|]vm$%%o)]_bbb+Oy6R9'R|TAFQ)Z 2Q1tpAOµvՙR=P7!_ {{{\zǎ <ުDtOOO>}-J=Ryyz7ӧ`3Ky<&OM6aݺu>}zNKSSsũSr666:u*bĈܖfff%!QPPO8/Ǐrϟg{ڷoI&UVALLLjLܾ}#F… z*иq]_BBjժ.bS111`?#\.ڷo^ߢESL&S>R()N>GV Eha/,s2Jש2x) 2hj6B>jVZB/_Ĥ`ذaX|90}t\x2Ledoo+V 66+Vp.qk֬QCw-p8:u*vb@i;]333p8OVڧwި]6LLL쌰0w}+WbС#._mA&aJeʹw4i/ƠA_]d ѠAp\̞=c[?tVVVl… qEcǎh֬ڴiC6N:3gΰ/amm '''\v0 x$ÉHɖYVB託+AT!Rv-+.]x)5xDpB/z2RmlܸQu((ٰa,--ѫWr9^\\ߏxٜ ԩS8<ƍ~1 ?yIq޽{UkС޽?ӧOʕ+M>BVV0Sdx+: m`e? ܉,DA;'!<*pE_||BHF ՜7N:ԩaÆsΪR۷|> TW\ PsаihB 8h Hd .hG=3/+qe\t 䟨7o.]TJ20u> KKKUT'Oą ʥ|޽ ܹs]2do(&T{2 W^>}(ͩ[Y={_~m۶E^喽 󡣣S51cF].S^))) ֭Ï?P䬢DZ&\kʰi(0&>O)qYZ;X[xbUA!_^^^HNNotԩSY2uָx"nܸWW27h999ػw/6mJ}\yݻw!m3R69r܍u hRW]ÜW1lMhXd:4F<mD4=!\QBMj|ԯ_۷ϱm6bԩS}B!Zj Ge䄂޽M4zeίF:up( g͛ѿ:)=W , Y(p8Y,CT ^.4=!Qw C}IEgƭ pk׮~ؼy3ڵk={tJ ,a5y acc;ΎTR)"##sNCq}-AFVj3WXpfpUC><)S P-M)P F:t($)W2 n¾}0e899:$VBBƍ1y*T@TTߏlM42 cǎʕ+?~5ľ}вeKԯ__ա qFW ЦMøqjժU-ׇ-~W~pJWhggPm۶͍"T ^IJs}>Z9 aǫmJsWK <uMR(!:Jall HӧOM6Zj믿 W}iժΝ;[nip[[[hjjb˖-TBTJ,a#×塵<*a%tPda0⡡ 5MxT]C 2'x두),,ѣk.UIrׯ_ѣG>}ԴB0 =k׮/Si۷w^UA!5CAxQ2⣁BA卞(ED."+ה{^A['JYD!eB#4riRB!d2,///Ϩ]6/^vN^zaܸqشi=ZQ[j!C`ժUxo#!<~-@Wu4VtX2x7T/LJ@kGJ !jBݻcݺuœ9s~U9b cժU.͛7ñzjzJշIqQ% :I]5UnJש2x)T>wL Qoh@>B*%ԄMMMWFnn.f̘'OB"T0o5ÁyfH$8::}cnnKKK޾DSBHBp8Y~a;+d,Cv A48!Tj&<ÇGzz:ɓسgO#F֭[e#""fÆ ѣ+͛%6==ׯ_Dž 0lذ#Õ~,}$_&M̙3C̚5 w-uxWS^999% &LO?gϞB!e80rwBj\C*gо|r2-0TFjJfBHe]va͚5P|͛7)cǎĉfٸ>,--U}Xرc~嗏nsQ]vOݺuU:[[[aԨQ8wϟǏyޕa޼yJ]\\0yd_ԥㄐ*ESMu}5A_Su_erמ!qIB)bԩ% _7R'͛㯿QVnsMܻwuA׮]ͧ{A,_cǎEAA\_r]vŹs///l@Q/p]ܹ`mm#''ǎc#дiSu^^]OOO>|ڵk>ի.]@( oo~ @]]=z􀱱q:tu .\@hh(|||>x+Wݻ`K{KWBGG~-}% N|ݻwCWW/"\.}􁃃бcGt޽D%NNN:u*֯_ &EշRŦBDW-kabkqѤc~&.UKᨅ|!Cz=z4MBǏCD<777n܀/6mgϲ222ߣo߾8{,ѡC\~@QΝ; z ׯ_(((`:u ǏW--- Æ 7"""  6 f08|04i4M1gbժUￕC,hذ!RRR3 c޼y(,,Ċ+pmfΜUV quVX(*/{ÇСCN5jҤ V^֭[cÆ 矑PpuuŊ+ZpGGGL>6mBHHo! JȐlPoWQH $ .=DH rд'rǐa%ƍ1 ҥKɓ'3 0/_f̘o߲ 60az߾}LϞ=am۶1}e1\.ylܸq;v,dɒOKFGGGiYLL #v٬Y3 0Νc,--~111a233e7ndF0 ( F$1=*{ Z|2^SDœ>}7ne&55\/˙3'Nd"""J_TT3nܸJ]B s.89ħT\90y+6t`>#)T.!0 0TM>HPGʕ+(߾}buK,a_[nggٳgcڵP(Js%%[RJڨj})P1[ `24"PME֧)rfΜcԨQ2>_lN^D>[\t 3f@LL gΜA߾}?x%FRaůP(>yl4nӦMî]qƕ=g 9O͚5Cxx8mƮWSS9FСCq\p͛7ǖ-[лwrw5kf͚AP B@@d2ФIԯ_ՙ:郎;ѣ1c|}}ѩSbc +/__~Ϟ=|-̙իWC.y檾MJVǯ%3pƄf)p-L 7[5ciox%<6!|JK*ƍ]v{;bڵHHH v܉.]N8f͚)q&bff/_)nBdB.c׮]ܹ3HJJY͛7رc ]]]dee!**=vpp00aE={sss455񐒒RQț5kI&!'':::,vlقH;/̙###8;;r9r9>^ڶmmۢW\. GGG8::bHJJ£GpQƢaÆpww{ꪒ .]СCOO/~p```СC?>&N{{OSvm̝;hժo!e)#AVjG T9r܌(DӺBX~wXbptqBJgM6 7nd_{xx`hڴ)S`ܹʽ;c|Xx1rssK|!CEѣ ɰ{лwoX[[#22:::1cu֬YhҤ :t'Ogt-[ڵkO=vƍP(ؑccc?8·P(ĀЩS'4jJ͜9VZao{nM6ұ ;;;[[lAжm[hhh 00֭70tPy&?^i)InЭ[7 $$=Ÿ 4j7(Ձ1{a8s z֭[hx߿?~zt ]v10|\rmڴQ!T|"5Gg+84$eq'-0p2](ep-`A!8LyԒ*mػwo-,,DzzRkJJ |RbH*M##b%_x<Qvmv]vv6RN@Qѹܔʖ̉V:O)Mλo}_pp0rrrдiSbT,ѣGhܸ1 ˋŧP(b4nܘ?!!RTi[ b珉ñl2d2@tt4ƏW^<(+'brfV3BH堄(KbS]~ŪBܹΝeDTTT*.˗/ dffpqqQ;: ዎ'qAܽ{D%o޼ʕ+ѵkWx{{vB@^!'ħh!9*>`Wt !$h,d g֎R3PB]CԤ:!!:jxU[ <111prrBbb" ֭[xU*]ZZ#|hܸ1݋UTu ֭[8|0,--ѿXYY}1CBBuVt]tdk~jj*VX___vBJ@ ,Vi2؛h!j'(ED."<~%A[EVvBI uM[C[[X몢"wbAAAFpp0ƍqbZd2^Ǐ}`JOOƍb!==˗/v[A)B)qR|#C]S>, ~" aqRDEO"Ig RttUbعs'x<ЃT\aÆx /=Wdd$a8::VX,ƹspyh={Nǁp=LFPP~7t;w6 &P0d$0amj[,3^u-euIDATsU\ CWvUsBJjBj+899UiǏc߿<+㡡Ql|N::th2 k0J΅ g"  v-L }-.swB"cIm !*B#??+$$VVVpwwG&M`nn0 ݻCmطo>|ɓ'ή6bȑ#)&Nk)8hh#N;\ ap5L s}m?$V :_}!Bj8J !d2={G!((<Acr\~G#SSm۶ﾃobk׮EZ0zhJ )'qr<~-4SHE]y"FZESz}Nt O^KM#BHUG 5!ׯ ypss;D"JbH$8<Ξ=ƍW^/Ѿ>ƍW֭>ƎK3(J " 9 \}"F}K?L'gq'\Dr5By%ԥ qܻw *Cé\[.ȨéSpUxzz[n&}r{A`` L:u(H$駟 &PRMH)ɒ#2:r01lPו'b|(@RQB]Bo޼?lllбcGٕiNXBV2 n¾}0eʔRU\{effȑ#x:w __ZCѣ:v쨴N*b4ix<"L \mJ͑fD!-B V[ 6%H !:b1Ν ooN5C)Slܸ'OqI; \fׯq8t={={]vMSSSabرJ%2 6lL2|>}!&C2r @뢖ۯm̢B>ɁK `eT>քR]PB]GA||}мyO0&ɰgcʔ)J#rlܸRSNJBޓUZ v|pD(TAT!hdrnAzBUO!1cF GGGUBHqeܻw ,Pu(UJnn.ǏvhԨ7n\"<<L&Cߕ>>>rBM6!//ӧO/Q99!_MN؛ 5"C+ ;Y|%[zB ۷SK !PXXѣGc׮]ʒJÇ PƍQFi>|BwT/H&R;{oQcbb7$j4EcKԨ%$*F7T@Tw) 27Ԡks<ǝzg`}<+3p@<<}<ٴi}cǎ@qPabcc={ךB).U}ūw KWѮ!F Tȧ}mCK94\U$RA <) WիWA4hgg29G^^???z؄i^[[[ƍ$?ٳ2 _)q#VIdB!n8ap12"2,ÃyE_WЬF2 D@] [PsNh޼9իWv*͛7ӭ[752/PXX@V*FpYݻo^M)u{ y&/_˨T*9Y͚5_UVVٳt҅]uV*l۶ׯ3c 9ߺu+7od\ʛP"[T֥V57f$)%x[!J#TN'Rx֠`̙r'Yd ~m7oqqq8991h zVXAnn.۷o?d̘1.$$:u_2s2lݺI&=?.\_ׯ_#GbffV.]JAA[n?fСezm/jϞ=:tHm_}cٳgtKuݿzQ~}4hB=޽PzIvJΝcۗ:}vBCC3g=\ U "(qԡv5} ߌ@@U2D#UEwuAx35(prrBWW Yf$''jFEz8}4V⧟~wez]=zgϞO ._Lڵ˼,έ[ӧ!!!ϼ_~dggc"""t3eEԩÇsf͚=v{P deeoܸ+RJ:ٹs'ۗ-[oppp`ܸqk.._̼yJߎ;??So&]]]jԨ#prrsVJuSMRf~]$NHO.s%AhkC O_7SNׯڵk6mcׇЫW/׭[:СCׯѣ޽;l۶Mm~ctt4rؿMr BBB`РAh(IMM_RjUmrssٽ{71113tPW^رcҢE *//]vMFF?/<`%ݝ6mЭ[7,,,ٿ?OOR]޾wyGmi֬666\vcdd$/_\ڵk8p6k׎K.qITѣղ8;888gΜttJO jVZܽ{_w_|?u֜={{{{.]{WCLL jݻGڵ9r...$%%ѧOyԩSƆcDz~zx^c{N:EӦM),,ёydɒ'7??By͛ѣҡC~R]&L **J^ĉ垶GҧOjժSL!22L6n;＃k׎3f ?|w۷/矫믿ׯkFGG)S%رcj (gΜʕ+[-ZDձe͚5ڵ^ԯ_q3a駟n޼ Go߾,]ǏӧOZlɒ%KHKK+u#""x<ЛZ5` C^Lۍի!66!IX5ѭCv QS&rc-Z4 ɗ;D.ii*B)\(!&o".'EEE,Z6mеkWy;wTB۲eK򈌌C>|L ~,,,?Cڵ_N>Ν;Ֆsر6[la߾}呔D^^^Nxx8+V믿/gx"3j(.**ivڑĽ{J{ԩxbشiڃGGGg;wAHDDr0 СC㉍!?zxjm0a?cݸq|gaPg}ֳMrr2|'7ڵkGΝӧsg^|9 Trss%55l''\,--144SSSD^( ܃(lllҥ ]t!77W.ɵm6iР%z|Gׯ_ L0Ammm&244D[[UVaiiIiㆆ(JJ%zz_  EEEOfiiɀظq#wwwyɓiڴ).\ 77!CФI? @sssOMAA$=1۔)ShѢgΜ!77QF kiiwߕ ?~?7|?͕+WrK#--<233TݻGZZ B^_PPp[XXg@oJ*ѢE ZhJ"""˗/b f%.:uϏӬY3zرc9}49 {|̝; I)T"d+BxZL/#9EUPU*0'_" LAX ".g .vCP:u?uR IHH`ذa :8 Ã\mVb[nS;HʕkNZ^/hӦ\ɓrbcǎ`ccCQQ'N(q GGG߿OvvZZ###w/—_~)/OMM-UTF \\\駟\?5#O3gҹsg4iĉ}W|ׯ~^^^TZ7C{5kLԪU ]]]~7zJ" @m/uC‚۳}v>3(iݱchӦ vvv .]bΝQ~}$?ҫW/:v|@ǎy뭷psscժU899ѭ[7>3̙* ZTEϵoBFq ]Xuj%i,40ɣeNz~ u9swwcǎj{;wwG[[$ۧ߰a022Ç >KfΜȑ#P(5DҨGo> w,Ѷc;p%9uk4}GÃƍM4 ;nݚwҹsǨQݻwnݺ4oޜpGj駟0`jբQFܸq-[Oݻի+*&%7n}$&&$V5ĉOjmۖ'PJy111aϞ=ݛ;vT*ya=}v9n:Fw}Gzz:+Ѿdzzj}jb̙?ӿ֭K  SN|gqA&O/:u˗?S+%7RIFFYYYQQQj=  155-pbccZ@ϩ"'''ի\zӧOa60tPt޽{9s&o ,`Ӯ];>3Ν[! L*Q(%TF|y$>]ř44x" y! #Qnll,GsF9dY$BBB$:u ߍSS'&񉎎&99룥EZZڪU+{=6mʃ[H'%%q j׮scnn@;550J̵s ԯ_x-RSS,1޽{DGGSfM!!!\|WbaaA hРHe߶m 6ի̞=D}}D%4x—E2 D@] ZPЪU+f̘VJ(tΞ=˄ rZg^^DFFʽrtЁŋӭ[7=;;jժqmIzz:ڵcrwÇQ($''P(t>|gggcnn!fffGyiFI}6W^ŋ( իGÆ AOOHvIff&:t㘘ٳզy4)vǷݾ0 {SãIKxElK{ 3r) =q%%:;eO~t!ff ^CvvvfѢE K #622/e˖١RgxehѢvvvT*5kVB1SSSLMMiH?l9 $66 \P`mm!fffT\Y- Tj4/JKK5jPF  @bb".]|ԪU ___MFLL ;wD__tttϙ={6Q=#e]gdYݙYӇSy.SȐ>dzzCd~#kWS+O{pqvkyb$rYڴ}b@ ?75Njs~'-"䞒L>Nzy@1n) Uҡ!fF G'r'IEz"APvޭ&qS3f cƌ!??}}'f֔3~x Ed*ޣOJ8)))C;11_@q/+6ׯJu1 #3ۙWڙ8U}/lE*PG"{J Xcg"8u 1{ hKAGGG /}cMٚE׊YU*iiidggGjj߽{WQ@ĀjՊVZQXXHxx8/^$88]]]IKKCR'Gi6KtjהoWpt gZ0;MS,x{k+"Uiyʦf XwAW'S}w1hPo3ɗWT5h䡏Utcߧ"N,s<=ۂ ;P7oޤVZn 2bbbԒ /llli(z~~>YYYdffP([n!OKKRJ͚5vccc9g)_\U?`?\g0 PT$Q?ݣ>\KpSӽ؉ ?k팃 _| Jվtb`wG@}<"Ĵ$Y--JU@Lr!ty"~ Ozv>׽+8s%0Ax:w̖-[XpZdA/;;k>d200x <''GtP(䀼9yff&Jvێ̚%b~̜:%3'eAA^ֺeSkUbŧ_COo{sϩl/χusES07~-gȇIH\S#?kLq)%6D9z U'p%AF|BBlo6jmm1I)**"!!POƍiLr$$$$yyyy@qW%ض ,^=۩d=yy!7RNJK8t$;q~<חh@v9BRJ:Je!iYH9.-e߲ M 7+/ u5e*S <_1ISXj]ULwAxPÇqO||y##=-{Hc=p;Pr}Jjz*\{;'e2x—l߾땪boq/=<9(pեwNROZA^"Ax>>уu/\֭[aŊ'Pzu,--9< .D_񉓴Q JU[uuq٢:2"p$F6xX` *̧LKiS D@݋ZRAxSY[[ӡCYz5QziH)MHJJtСC15-9511͛7ԩS$22oz }}}LJOln^t4v'!)/6ZG[W˚TH.?5V>kK~ y`cb#i~A}%щtk8w;v _X B1P Ft驊 $66͛3sR*#GЩS'&O,geeW_aeeł HNN/d„ xzz>S3f %AfSe7b3wc}S<}0H) .]E:XY ,MD?A"jA^{/[)M' K.EΝiРAGܺu7yrJӧ))),[S~}M_ <--mݩZٕYww#}c<|dS!mgѱ΋s.(8V5=-Ũ:A$WHNN@qi'% */٤}*ܯWTE… r=7oΌ3puu}Hĉ'صk-[dʕ%>>|B`4i҄.]hVB± ϺGX%u n僕qfWpm} )rgocE}WQkZ 6ںtP111Q2\PP@rrZ ȉ/;wpm\\\QF/!!SS<( 033m۶j̤J*7n,y$))`iܸqL<'#,,дiΡ}6QQQ8;;cdd3Zȵkמx˗/ 42qD=Jf3f *J&=====LLL #66///DGG{_t;֗ױTEKIIԩS+W|lyyy޽g2p@GrssYj:::|'RTTĚ5k055eԨQ-PެvfN$qqqcРA̙3/Bںu/Hiii/t7͛7uIcǎ ܹsRAA 7..NϤ9sHo~vҤI>$nB-KȊbslE\)ދIVI{HI oC]tuuՆqCkooo93177g] pUhڴv5j@KK OOOMƸqC{83p@OƎ練dȐ![sr%tuuiذaC{{{ZnsT? OOO/1W{ɸ%:|0 r?.գ8mmm222ƆN^+WO>iӆvJT"at֍CX~a/ѿO ח޽{ӦMavvv 4 6f< BEurww'""BmYDDSKCF#͛7磏>bÆ L06nz^R)RPPLc֬YO<YA_^B,,,`ggg}5j9ԹOMgeeŰah׮]ve޽,YDYZZ8?_o޼[nqakƎˑ#Gˋ;v5=vR,T*[n_2vX=ZZZl۶7o>vP1J<Ν;4mڔ)Sz*7oz,[$Iڵsα`\hѢ7YG80"SBq_`9EUPU*eUL8Aj BE_~5sbnnNAA6l`ʔ)tCCC %2:::Ҿ}{mơCXlYۼysk,Y"?(А 0jԨA56mg޽пΝy*,,zm6̙6$qA '***R;>}طo͓{zzݻ7+۷ … xxxжm[>2M––-[xǏjr|~G233Yx{ܹ H (1qāx"XWEh = q*1H(PD@]:uD=h֬zرcTZVZooo @:upvvfȑYfѴiS L=GÆ c޽oߞsy 6mvT^RV-\]]>|?E >ɥ\]]qsscРAưa^oߞwyƍ3l0LMMXt)M4?Z\۶m>|8ƍcݺu;ԯ_cǎ $oߎ$IѣDDΝ;;#/KJJ"((޽{Ν;ZyeΞ= טY_~)1OSgɾ}ͥo߾ܼy{.&Mo߾萛˗?ӥK8{,ZZZtOOO\YYYsm9wx>Lff&-ZQFj}xDRqQcǎj2339vnɉN:yPΔJ%.]" h6mS~p6nH*U9r$666Oݻ|s˗/gڴix{{kV +~ yJdJy[y`C+RH:Fiӂ N/e ~GѣG5r_iV?G}ں4.]E0-fX%bf,[Vq6ouV^TuRw PPӂ $z_'IX[[kiiij^7\vLMM_ /(J._L`` 4nܘ֭[Szr?wTT6mАQFe~Jņ >(gggxbx뭷4v_Uz_Itb!kblAoF^PLܬZ YE Q;s@WAD .lKKKKc4צPX^EE" sꊟ^ \vɥK} $Ipf>yJ6,Ea$=LP:jDGKN D@222Xp!oSx#@hh(?o)Mtt49shܸ1[5??}@߾}i߾3'Nk.Mcٸq# ̚5B @U2D \* #/KH2q:ڢZAD@]222ػw/W^%--MޞjժѱcG߯ N>M`` ѪU+*x"[nˋ!C`ffV}%Ib\r?DGv͵kט?>NAx$NHOsĈJ T=]-3LAZn.5p.kA  ?C#""hܸ1~~~}@͛IIIaB5k(((`?vÇs1-ZƮW^%'BXhÀs?Uť|:5*)< $bYgjQ% IԂ ;w!ժUtsy),,>|znݺ=sTV\;FzAAAڵ jZ J $*pСkOHyXD@v 0y򜂇D 9;gX B o, $//֭[Rlܸ'''\%颢֭ݺu{vW^e̟?M_ r%QfK-^GѴ{[Md f။E t*6σ ›FԂ QT*<;<< Һu'&hl۶(FIz8ΝcL0?q7o_3k,5}J+xzx:}0]P(q$XAMG=?\e6ѩ$>|;"A('"p]8s UVϏ&MhtH?T*=Nٳsg8q|ժU{=YlSLVZJH)DzR U`m9DXy  P e"""ݻG||U+fUSւ eD $[r~mjժJII!88={0m4+ *`q 6O#m/l߾ׯ3d5k⫯ʊ &<>vFF1o6ڵmWB|37ii})4?2Pې3(#:5T슫eM tEyr{HPPnݚM4CI$_i޼9{ϱXVZѧOR777ŋӬY3yM Ax%OUq!2?/l'L($s<<<:th]c'66'FДTH2¸|F_ť8w+Nu 11^ Ey3gܬ0 3)l%!!M7Cx jՊ-[qU*׮]# 0|}}2dO4Bݻ9s  u/ޣG0sLjԨoΎ!CunٲFs'Vh ʧ~ʜ9s8%J:1̨|"̧OԬR7+/S#s{j[zaWB"BT*::3MxPXXXfǻ>>};;;ZnͤI^htE9{, uaŊ/<=-[I$IDGGǗۃ.^Ȳe066.)ammM066f͚5,]] $:u06(Ln0=6\}jVUM$(vN[ya'˂ O#jA^Zٜ9s?VM+6mDVVӧOz/|̼AGRqu ~ 4zH?)J~w;FϞ=ԩSHNNfŊ0lذR͛,X܇_߽{}9ytޝ۷g@-#I.cCu3HSV֡7-BOG6q$&gcac 7E`-O"+gR ~~~?#W+ANpp07oݝe˖aaaQ&ǽu| zcǎߟ > /uB8UF ݻm$ 'O)Ѿ!:|t]Vtn]8Nٻǰ1c}SM7O jB ...СC9}4ÇO>%=VRR.\@GGmr3fLf.[n1tP.\pIOOUV,\;;;ޗ瑚ʖ-[>cǎVZev젠 mƔ)S]v9{,g…U=9Ss:T>t{J2rPLjWc ja탋e Xn퍉~| D@-Tݻwl2 _~YTWm HKKzIسgOf}unܹs3a U'ocEsOcNR!щJ:5BWs9ȞV޸XR<11 h צM~WN:ӹsgyIxaP(x"rrr{P#GtR.^( _FT>u8qFF]N&Ciݺ5cǎRW4KDD7nښ%Kp炂~222Xxq ||/T{W'BXhà\{3T\S@چSչɅ'0SX y cccmL<{{{|||h֬7n(ձ iܸ1nR[>j(> ӦMחVZ₫+cǎkO4 iѢ,X-[0`jܜ/B^j*{=9)V^^&L///Zl͛7>K.4i҄.]PfM~gy$I,YU燧'#\ǎc…,]---ϟ'|Bv^`:++~~i0%Kg޼ycccꫯՅW͛79}4 6Hbbb>'Nk׮tuuѣW%$$pQڵk޽{x"\v&M_O?0o}QTdff8|&MpEmG}Dxx8gϖߙ3gԾ``kkKAA888Oˮ]p UVrC_VXl-[,u9=oݻ,>SΞ=9ӦM{50p@ә?>ݻwZM߾}4ip';;?gRJ9||78p1cse_|G?˗޽;/Y(~GΟ?. bܸq?rss5jիWgܹ@CG0aB>̟?0ׯB(Yp!/^֖ʕΙ35jT*/9t 0@n?@tt4 , ::sss:w̄ ʵ[zN'Bsǭ\IԪ՚.OZ8[Tܝh>8~e<}07tAʔ gllcy{{s<==9aaaj:::0{h߾=7U-8Ƞ~(J9v옼^KK ///.\ ?ƍ%${~`Ȑ!r/xNNFFFj tuu.qM\pWWW kDDZ &WWW,X ˋB:uܹ3cgoo$iO+##ھ}; 6dʕ2[RqFYx1WTrJ<==첳裏9sfyJEǎiР6m@^=z`<|SSSFAAA֭S|ĉɓ:t3fyfӰaPT_JԩSQ(̜9"~Gn߾̙3dر\E0d駟(,,dʔ)( {=x֭[4icƌQ{Oxzz2qDׯ[2b6nHvv6#FZAƍgʔ)}>DDD#phݺ5P}4oޜ͛7ƴiӨYѣqss# ={`֯_/?߿?&&&lڴ Bɓ7p@~'ܹöm,Ν {dUC/EP$Ae;UM5s*yำa탅'P6$Ax z+O\HvvvҶm$k׮ҀJl~jժҡC{J)))j &yxxH[Jmڴ=*8qB:q℔(߷odoo/m߾]:zԹsgiI&I-R;t-I$)''GjذԾ}{iҎ;zh޽{%ggg?#K$I{;vHG:v( >\oر҇~(Ioߖ[Aɑ$I.^(H_}t%СCҴi$J%I$}駒oI7n,ٽ4/Xiɒ%Ҽyr;Ovv駟J+W 3R+WJk֬4}$Iz۷%kkkI$UVҎ;~I۷$ItQI*,,知FI$IIIIvrrr$@w.YYY NNNRHHA$Inܸ!Y[[KVZ$IRΝ;իWK=zecckפڵk˯/Jׯ_˓]&[1cںKSN-ϵk$[[[@^v~֭[K5k֔ڴi#iFj۶?IKF}BJKKeoo/)Jyŋ ʯ7n,͜9S33F޿{pG̙#RJvZvڅ9˖-S+ =gڵ8;;ӴiSӧl۶ /oٹs'7o&--իsYaÆ>}uֱtR6l;>o}СCNHH`Ŋ2hРg:$I[Jĉ_/fҤIPe@}h6_8..z*j=焟?3~)7r[nCy#i+fffr[nUbgoРk~>}%K Ik&33R[nA5Ԗ;)9s>|xo߾M:uZZUVl޼ r![nNg)~?FajjJ޽5kSkԪoIԶov þRHD\qi=WYִZG3p]#<}TvA* UI͚5+v6ر'L ԆPwȯ7oN{Gs3iΜ9j1c3fxjOK,oٲ%-[|>9#G>իWgŊO\?vX7Kزe ^^^,_\mlYq~- M6ϼ/BBBsU 8_Umڴ^-\N{=5KΝ;iٲ%FFF8::baaAddQV?ҥ NNN˟XZZ\~322ѣO (~UT!::Ϗ:w G;;5kְfn޼ɻϺu랹.H &94+)YE\,]mC*`IpCegp }]C[`el'A@"˷ZYd ]t!44TO̙3{rq.]w}5tACYb+&MbҤILC9{`ɒ%j%:wB૯(u]"##Y|9+WRzuO.ڵkk֬a8q-[nذ!nnnj߾}[miԨ̘1C֭[\~T?|R)9}4;v(]Z+ţ9s|7o({BLLQݥK_.L8pھk֬O>ĉlڴI-7F-f֬YrzDD$&&2g|5jԠFA[Kox6ʃ Ro !ɱE+hizUZh`L+8{p# g#9'.PA'Ziժ'00m֬YÔ)SqNɉϿu{UXXdٲerO`y$۷s-Z38qٳgKGj-ZGj###o? ڵcȑL:(NBΝ1bѸqcJ5kRF ƏÇ|999QJ#' k6Ϛ5kP(̘1<Ҹp[la%J,,'xݾ}s99(V(n:ڷo&7nAAA0\<==ٹsgԸVN nmj5ɳT! l+kS5i cL C[K k8jI %P /J*DEEH#QQQ%0iZFF۶mی99Xbnnn̘16]iDEEf{=+ֽYv-9iiiҲeK-~Z? ԩSts#+Zv&$"gb } $2%lM5u$))aŁvU_ e@ ^B`Μ9tؑnݺi9K?ߟKbh/lܸF,elڴӠA:F\\~)ƍ{%z ͛_YψVujݎWWH纆늌%9;)aI*Xk! #zbhhٳYloߦsθ9o RITTG!&&ٳgk4fΝ3x -9~8sy^唔-[_`֖ {h!,SPݰdM!Y ME=%`٘8`c@rN<)aDa僝AC- BC8w:ХK {/oӓN:i)fժUTZ>}z"`jVeq"TACLEMKIvj <}7&kA*Axmܿ 6PTTĘ1c*tqVV_5L4h+ >S֭K~*e!""e˖=W&sA(/:%);Є8[T֤&4t7JLmx&F~aV89%kAʟAx) CPPm۶EX-Zзo>RdŊ1z kYڲe !!!?իk9qSP^$C0kΑ]D58u/d"S+G3g!k ³ ϳuVj׮͐!C011󇄄w1tPZl)**bժU2uWgرc#hJYNA)Dh(fPqRL #!V^T*kAʅAx%%&&i&222=z45jԨ6o1cƌ>IMM>@WW[( %ZyJpY8/ݻEi O|:1,X5S"02Rp:eXO2!ccgK +!Wocͷi)kBL{C߄l2+&kkk:t耣#Wf8::>T*SNL2==|YuVw):˗/_fΝ,\Pӂ)|Z4xj0 `oFsD$tZjefhN<$2%\-=f=F|LLt3׈PGaĉ"ʅ}aӦM̟?qM6n܈%/~7/lݺɓ'I7X~=}vvv$2{ /]]]jԨ#prrz} $N)uӧJXjkimkc;<٢:nV^h!ξL *S߱9D .5p\uQQ:bL[[ JLqʎP hkUVlٲ{! aaa 6ƍk$Ib޽:uɼ;wzjMƮ,===b<==56@),,$((O?ӧzI8nͳEb@sN\;GjN"ubbyabPz."*'bYgb O%7J›Ro/IǏgbŊ" Xv-,Y3⛐+7n\/״.^Ȳe066ts(nӦ 666z &Ip*"Km|?25Q6Ds&樨Y17CSr zC8[TŲAx,P qwaӦM2o޼gY222ꫯc޼ye㚖ҥK8p O=D0-|||֭w{A/^N -ܭdKpYRrDW)u원[]<<,T:z|;W=҅͞+hZe 6G4rYZ8}4f͢+VիWч|U~aL9+Y<3ZrѡI70W.3PNׇѡQWoEk;=Ϳw?TmԽ/a˾ms=}1^x=!$??ėxJ5ɗ֭[Gǎ͛7ٳ'k׮}jm6Ν;ǚ5kԖgddp 4tm7ߨ- _~lܸf͚=_qqqqlܸ]I]  K i}8>:~K<㓨lQ<~3'2pD?|fб[{V.Y jĉtڮD[$`Ts 纖ZѺCǮ#=-pA(GZOlRmYaa!>>>ܻwTǸswΎ'n&z!kJŬYpssc޼yk׎STn#8::b`Pt]ưa4rϯŋiܸ1K,y)iJO?ĩSOʬM$?```1c4} ü"Ns:f!Aw <'CJҵ E?H и|C;{`ai'0ෝдU9aq{N @ )޼uS$pn,Bꢢ"V, :޸ު ?~%viۙѹY[7uL>݆Z+CP cǎsM<== //2=ǎ{/_?7oJʼn'~ըQ㹮4ILL%>˗ٲe 5j`ٲekIj*YhQfߴi>d֬Y/ C뢏EŎ5_/Fx6rwӣw7e5&nEDRY Mu-9q4peݜwGzkX&addHNv^iܢN|=mk;.ѯ9Kxoy244k׮Qn9$`'K ح=)I);kWё1er}?J]qpڒ*6r/Z(^z{)fܹsx ڹs''NĉHD~z>}`iiIjj*w`0##֭[?ܻw7n̬Y={Jm~(W*\|0~xRSS {{v={WPPPbcc:u*_~%4oޜy]É!..t.] @jشiy~wyǓLXXݝ'g͚EǎF*2H,_[oŐ!C*yZ|G2:r;vT{ض|rSh۶-m۶C,ZHMm6Ο?\*J>c<==wePoݺ/Bӷ 8s3SCm:kѣVƶ9JRvIDAT$R~` .U+νɱi/~ǰs#^ڲq88Pչ*1Qw`#lmUgGo==!^v%ܜ\NcBe!3}󗣫CAQe;A(obȷP*ݺucܸqdddBNNGQQQ\v ^RjU꿖\|#G```:uɓdeeahhHaaa\z/qƬ\˗/iӦXBnO\\aÆ !$$Ǐc`` ;vܹsrY I!dpm_|qqq##ؒٵk.]6z <<<8x Ϗ.];Sf* ܹSS ?d…jR_:>}ŋʼnKS 554RSShԨ.]"vtuuiҤ3;p@ػw/\z̓8n޼B[Uj<DWK~dH-=:4ض\ۦkV&=m6t}OfXW..Xp%_IyyZj:VMLMmR_AR^M.xquyٿ,P"I3=ĵ+Ֆ)A]^R\2~~~=zDy@>|||hԨUV%<&&-[SNF@Ñ;w:::2vXudd$׮]חիWF=ӧMxx8?YYYXYY1x2$.]Ehӕլș96DL矁tG t03SktCw:}L.zv|E6v0գо zk8#& C__?vó8Ѧ}>e9t <J>OnYh%G P;wcXXǞ Mv-=斕Yl @-Qړԓ붲⓯hԼ!vARBRWA( PjzK FAXf 6mbjMaa3ޞxe$wpp~lذAmGqwwjuHCCCJ^a֗ޞe/g^$I 87a&MD Jlg``!ٺu<ѿG8p v"!!v1z2M믿&**ŋy0}M֮]ￏ/ǀXbEu4jԈF 6|jȉJ%:uˌ1&MеkWBCCRNg (J:vիW1b7K.r΃,X1chܸ1M4a낂:vȵk1b5K.j;ѣtGGG3kС3rHhٲ%iiCH---,,,k׎PFI رx>|]㤤0~x6mJF6lW\?tPLMM9r$hBTܦL~'cGEE1|&L@iذ!C sfG 1c 6dO,y,l]r㾒>뾄/GCO wK/pNǖLCۿ}v\8}^8J0kL}1] ,\IKM4nވU?}v3jpVU&_g/t,eO]v::lص̌,N9ksc!jsd*'dԤ,r.rEj~mϟNʺ\r*U¢E;ˋ]vѠAi޼LJ:u0a.\۷YrZоfv$It҅H>c?+zbذa|dgg3i$̙6nnnٓaÆ|K:uY&&MbܹܼyTVZZZpeLMMr }Y޽ƍѣGQߧUV1c zի'**$ D~~>gĈ4o===/4V\ ӧO/woaԩ/E]^^}ua̙j֯_liӆ7ozj>NYw^ټy>--kKDDϟGKK ҵkWF](,,dӦM]U{prrr:u&M{nظqJJ ֭SKеw^._6?GO:%]66m"0ػ({o$B fCD@xAP6, bTH %dCBz}ȏ5M<ܹ3=s=/}Q:uDNXn=z\ljj*_~%˗/'%%B|lق PҶm[ U׼yskBCC2d{c9R킂~7u;v 44֭[CVV5uִnݺw=@ .RZ="fCg>\Uf^*B03e=<5nF Dpϻh֪)Z=5̜tm]{tk.`#o;w3ϕwg"D}#0'''^|Eʭٲe ,য়~gϞlڴ7kc<ѹsrA#M޺u+g楗^E[N# vPP,[ݻwcggǚ5kpr*[Ӵ~zVXɓ122b̙Nco_tttضmsᥗ^UV|w͒=rr#pttԸ{n:æM_5oeŊC6m077#  ӧe422b…||GoߞX0dȐ7))),[ &hL+wRpqqaر,YCFwEZ.]سg]S(aaa\x<pttԔ'NЩS'/w|nԯ---5٩ q…r1cӷ:tH=ŅluF #,,L~$nVVV`{ˁ裏ٙ ں\# IIIٓcҷo 7'OM+z~6uf0BkMް|Sxqqk:]/PJY`o׮FVi9s鎁-Y}K._m0k,f͚@۝Ogru|Ŋۙoܹ3>ofvxqƩGE^ɓ]^xFւgffh"Nǎ_&44蟺2+ ;?޽;P 2c>|8ӧO{{{" : 6<5#mwr)Əݻӻ4h[[[1o]veƌi<ȨǏϳ{nlzu6lÆ #==m۶1zh "?NmkBe㏷M zuwWjVמ;҆zD] )-]:x1!D$؄ w}[oU#t^^/W^ݻ >0aƃz~W_͘1c… ٵkO<ݻٿzׯ/ܺu۷s!6oެ1ROr{婧bǎ:tH e<<Eo"%j;GM5k ckJK^q6>+L,Uj=(KI$P !+ywSSQQK.yu$X}3c >S렠 VXA>}055%779shL=u:::xyyѱcG>.K͛%000`ڵ4n+++qttT'cȑL8ooo6mɓW_3mߋ &MBWWXv-=G᫯'''ڶm{6o&qѷo_V\?/"zzz`bbڵk]v/䄍 |y >ر#zσ ׯ^Օ4ZhQ# M h_&\S\PmGOn~5]::2GbvܹAiDH,\fW.ưwp #=;LJ_}TGGUE1fk T7Qw⥗^pm(--eŊXZZ2qJlFue"99Y]AdffR4ܹ===nݺř3gӧt|eܮ* ǧbmm}i)))X[[񳞑]*呗@%RRRyiu esMq|lGOzVth*5+鿁mcu ]\Ząڵ%[ztpN64'>".WMvWD!RDEEiHV;w.L:FiJŚ5k_`U% f^e{9<]t)WGNWX@鮟u{055}zNNN5Lxzz9ЂVыFLU9uv’!(K]6v0B]X灳xן#OPW@NjUW'"9IԸ vUiB<]vU[{ ?fUsMf͚Urj8q"qqqt333޽zݮFq "0HE8ӯgwk:7 |fu\f4ck_mwιnJY7nLX<6j(NdP+-)%16sWT+*((୷ޢo߾Yv;v`Ϟ=,Z_uڻw/[laڴiZl©S3gFQsSN9*"[ew,SEXQ -fkjmEل%޽{ٳgP:::ӷo_FXJJ /ۛ'k+..&**]vìYuRdÆ \p3g={sN͛Nd%3ϰn:zSp+--eܸq\ ,G*+ʡ}S\\*Jɕ0Rs j6T{)1'''-ZYv- ܹ3'N邂V^Mii)ԴƮѣlݺsJ0}$''qGUombGd+L@Te7ҳ{M߉:{ҵ3 wJEG,XzТNN߯dZ{j!Dp5>Cʀj\~)3f̐`>Fܹs U S*$&&o>N>ͻ[ۙ:b"7HE8Q7ɢnxjVWtD?BP !#G~z^z%Zn]犏祗^e˖ھz!33͛7sYn޼-mڴaĈU}?i9ID*.שൡլ̈4lⱇP qoP !͛7_1c <Cyy8 !jJ"u_XjO9'54Iyyy\͛qG%'<%%%wݞiժG)̛7SSSmߦ֕+Wسg7n )) R.4]=|l#6#cp0w]3L k/&vBI֚HK1!D]$]rիWӻwZ;'زe sZ۷ᡤR8qÆ cĈ8;;+#Lzݮ:pBfϞ]j=]}|iOlUܕF010~TwA3XOI<&3$BԪ~ɓ'ӼyZ;oxx8| fIF5e߾}xbkwM<\ӧyyy/L>]]}]}iOLFGbdN#ެ֬@$n!Q̛7^zѫW/{ /s[n=s=ǪU}Kj|FT*~'~WΝ[tTT1g׮]L8QiQk~Qiz7 ť3Z - 1w~cl$>ZT\LMMxҤI;jc|7q{{uH#ĉ&OLff]OJJm[aa!+Wի,XZ;wbb"+V`ĉjVD/BaÆzjزe ƍm۶\xQ_#<<\/?O>e˖lٲÆEѪU+|||xٷozի5vr׵ahܸ1'OYf ۷o磏>Elْ_U{-[O$| | M4!**Jc;w.WfΝm``@޽9z(O?5߶mYYY̝;1cSOѾ}{ZPFŬYd̘1 <,2e yyylݺW_}qƑ  8pQQQꫤ3ϨWn]ڵk?>| ǏĄ}GgC^ۛ^xKKK nݺSOU3ѡC*_Y|2rZ=rK^q.v~ReIkW(9jW !; E{ؾ}; (wޖ˔)S/ )) === ׯ_Yf:&>>gg>iGGG3o<|||Μ9CI?_l5⛙Q\\6гgO֯_Ϸ~7ݻw~p_bcc5֯OLLL7|_=z`֭UR&LvwD58u%%%9xҌ,]Ej>=q s߽ݻKxDbb`FKtMNa~Re֏+^6O\ftږcB@j裏2|vɠA4}-XBk_\:::(JΎ8ڵkWSRRصkoF\7'OfҤIF~ׯJ;v0rH.\@F{;QQQl(Qã0` @Tm6|I.^oܣvZ 2e҉GOOSNCvv6z߇SǏؘjǏ~666ӧQNN;v|[laٲeѡGOQ; -hڙ,).r(ziNXT&XekVK1!DC"#Ԣڹ˂ 4{CbHKKW^c8qBAZZ999:O>ɻKll,̜9>\zM6O?]mӒ_uϟݻbݺu>~Ŋ|檃CCC *tԩSyz*̙3 /l2~700аec2\JJJke^zoK.1h {Jg}...&&&F< X|]CZZCQQS P(z|6mԹnPX222*!!:J"&&T*zZڵ }СCOddds秹jܹٓȓO>8<'Ndͼ;|w__r={333:vzy^ذa/LJnݺ}>w in?8NSNK/qF&M9r$M4!11={L??r #Grq:vH@@'O槟~ݽ?=m6Ξ=oQ͗_d޼yw RRR o߾9VZݳryHMM%44OOON<޾{nZn~c1e:tرc~pǎ^ajjw}Wn ڵ+#GT?~:зo_FGJDZZRہy^^G&(( &_Ѿ}{ D=5gffңG^|Ex wʖ<1~x5*DFFĉy㧟~OȊn]i En2?uuԑ_jI<&hTBO?.z6>?RM:UPDVTVuM?n޼Qo:tjԩ_~* @UZZRTwު>LRT'NڵKժU+G}T㏫U*J{n*77WqƩ,Yrk4hj}g@URRJRJKKURoT_ZJյkW6Ξ=rvv9_~eܹs*WWWUAAJRV^P?^ԩSCBB4ʕ+UڵS7oSٳF'Nzg?sMUTTRT_]5ydYYYJ}F*OOuUteUvjo>OWqHuhU~QRY՞[TRΪ }sbkkR\\y߿|o߮Qge̙={tuu+O>Y4}АsѥK*_w}nj3ԉuuu596jH]f?~3v_ҥKi{{{z@FFWokҤF_q55|̚5+WhѢ `ԨQЧOqr)WGIIT_ {3g\7sFO:delK{$r1 %'3u&g&v5ÓNzO-ꃎLB4,A ʥK/y7]zE#|nn.J{XYY}vT*/^c~222_nwoѣѣ:u駟PJ\2224 <Aƍcߠ,ྛ_|}beeEAANbժU@YFP6ަMZn͘1cx\]]yWxW8wڵW_dfZm@y$q&!lڼl^٪{evp#=7 D_}s-S,eF߿?tҥV+ `悃 y9$y I'0.6sئg}-egD3'rL "q4w2vxXvh'%uB܏޼yiٳtY]Ofͪ5y& .'m޼#FT:`mm :::G5kFHHǎ#>>^{h1tڕO?T#{^ŋу3f`hhH駟7n3qD&NXZ‚H۶m:::hBc &L@PpqXxz]HNNرc4mڔ˗OPPFÇ'22'ObeeE۶m133Ã'xߏSNUW01)nsÃ%K`nnoܸATT*p"""x]vxzz2rH\177gڴiO>$rڶm˫}VTe>wzXj兏m&fdf~KdfTbon©%D* O> ]l}֋Za퇱 W‰ucS -y\qi璎J{؛y) D#=/sJAn 0Q裸z-ˠAQOر={hѢ UDNN.ݻwgȐ!ھDFƍݍ {0`hǫL:+++,XU.8drzzqHi_ƕ*}_\SO};֍NM| \,= thQcJ+a$ڵ &vھu.m!jLdll̬YXx1???YS-)..&**]vìY-.,,dҥiFi!0rH{1tuu իZ010Ok?*%yi&s>8E%ufj*:-qp')S`o} lMԉǒnҥ]̙3 xktj !DUoαcHHHvwDFΝwy(rIM"=7s#Kui}{Q"V,/bgLqi!Fpރ{/(|1Zv]m!jP 166fĈF*Jg}=#A}plkw5k_<}Qd+HM&<%yfԈ蠃7"ΡSV=8+~fute즹su3!$BY| ̜9Srmuk.ؚ:В|ɤ$r) f&v欍@".$ 8 ~:gcid}΄~vM3u",(dY-$BI ̞=ތf b׮]PZsc}ܭ|pARK)g/fe6iL<5Hx7+287&v7cmbGOY-7d ?ٻw/QGR9@Ԧ\f͚ɓC’kEn2&=EFN*xL*F5o^ԑFͪ eFs5Ԭ2YC-ĽI@-SBCC矙;w.))),^ooo jDqq1[-Z0vXmwBTOGLJv9Eԑ-x:-&,(&JNn8,RsqDZ2U^YxM i҉ܢ,"9x4BWSuuti{3g$Jj!DoBԯO>M+Fll,SN_ zj_O?D166ɉ?Zۿvzڸq6l **گ.^Hhhhe"""1cjuLAA/o߾L6ƍH{ٓSzjk<%\N ;3&L0ű}xZ-RY - Gz7z@Kr9ʁ?O>Irv<%ʒ -iڅ=O`vb3"Qw=ܕ ~pA Jk79997QFeƍGNN&D#.]J^^PSB9{lѮ]; 2dH^O?ĴiXf >}BL{\\ΝR]t~U״={ʬY011vwl߾ooo Q5kƠA_ݺHq&!Qt ro=]=]hԎ~ #+39pm+o'*2Y5vMFVq Gw)΍(Tw M;3'&5'&oybnnNΝ*`hhHǎ177bB4<2[TRo߾|'̜9?3n݊== sr5"##0aFFFYF={ҥKqr*[5c ͝;Yf1c ><K,QT*O߱ѣGӧOz-VZEpp0̚5K~ii)| ۶mȈ^xaÆ̚5իWs!Yd 0|"""|裏zk׮СC2tPNꫯr-ϟ3xwaҥ۫Y~Ĕ)S+2WTTٳg8::Vgѣlݺsbi)L"K/`[-mݷp>.q B3Z`fhMR2HI",%̜믫;95܃Upȴp/Ȯ)nV>rsH׫W/@!!!u:D1j(6nX 9~8 "22s1qDx~:K,!??I&sꫯlj'믿شiW@OOnݺиqc,--yiڴ)NcǎQPP+;vTv8a4i¼ypttdÆ ,Ysz)[ZhAaa!`l|/Eƍ#%%EK/ɓIzz:-"%%wy6mVsfmmo{|E3ZyKT2n8n㿁m:H-Xm+ALjN"y ,9cel[OE4oL(tܢlY]A888j*mwGI%JO?t700PƏZpêf͚T**>>^e``JNNVaDަMTwl?00Po_ݻWw}}}}UǏx_uVݻwկ_ԯ{:xJR;_~]eddR(%feU-qek@'^NT%lY6MjVW\pp06mR(B'___y~{SXXP~l&л߿?3fG~I7jWWW~7u6spp 55b؄:*^߿}FwOڝe֭XXXnaaB@RI]h!C>ťE\H>A~qB03z5 k?R frE].N{f͚iKpQ!^^^О<󄅅oٲW^y777tttx'XdF̜9-[bii 777I#^xI&Gi7o_| cǎE__^zHx7ٮnɓquuEGG~Ei766.-Z0e5k_3`h֬/2?CC:'Ƹ$oa֬Y·kcccl?{G`` cƌtY4عs'?uF?~g^a޽o߾^.\P'^z1vڵkiܸ}uβe}ҥ_ٺuu`` >lߺu'xI&W:ֿV麒x&a틇/*J=z})4ye^+殤dvkoz{w?'#=71W\؉c4YMaGN-d̝3wwC|?*>ˣm۶>|X޹2rH^~emwz>gYeN˖-c׮]̞=\dܢlbb`J Vz$d(r0103gM+d));ki;ӲE*TD_&6#p4wt?WZ5-w( ̜QAFEW\\Lzz:T*q}vٳ'ĉڵgy$6nHNN SNjѣGg@Y84inÆ Zӓ^z?@nn. ?r/`ddĄ 4sNhӦ [[[u_r+W_[bb"7n$//AѾ?_nJV((0x`ڶmnƪ_ߞs/nb˖-1a>6m"99=cR˾HV#}ܭ|pAtrFnQ.XxlNR .&XؘWfull,lߜoov7DRQIVVVlٲ>MҥK6oΝ;ke4IA~~z)ɓ'iӦ nёWcccK~w{*1cƨGbccر#VVVxxxsIRSS8~8m۶%;;{{{ƎEoyט:u*ܹ!C;vccc[n*|/=J۶mޞѣG|r9spEh^u뜜zʕ+qvvSPPg޽~g̐!C4CYH^V_Ѿ}{ ᩧbʕ}m._}i3}tf̘!:!#իWv*g̈˩a}}'|ıuK8ʍ(:{<頃=-KwA8B? KER޵ WK/ʛ9wtMOaIGbSU)Ұ-`niN֭[h@d!֭|e#aIIIA>}:oӦMF>=z4^^^m7dҥ >}Iƍ`_~ꬳW\QL69s0yd ?GVsNtttx簷GP`ooω'G__WL:yK/0d5jzT^.]{U?Dx74ٱattt;v,...dffbmmJ_~a߾}qM._ݟ5kqqq|w}PaһwoL{s=Ah֬FQ#+Wؾ:5jbffo/* ~Zˈ44cH7+oܬFsH;ONavfN&1uWK/oxs#+-h'%־Ki]=9e:*ސ#)GGG рEEEU:?_κuشiM6ԩS'Od}]]]i֬'NPۃ͛>}I&.Es5TRN>̀ӸqcN<~E`5NNNxzzSOW_Sp{zzq{ 婧X,-[TowvvF___cǎqM{}]ˍRիWYn7oC;v ### p///ϫ"Zjo777T*UxZcWRq>-]:رӕ`mb}sx`-OHn+HMAk]<}F\87gB6Wob3"9pefJ!~Hk.m׮]itܙo:::~^^^w̙3Yj+Wѣ|wO<sΥC-J緰য়~"++n:/^LxxF6;ӻosךPV*ɸnO`O۳gO>r룫[[_Cc>c5PWK/\-f*IZNp oakꀃ+fΘM#ܭ}yq1qK'oEHj!D&;R&&&;vh+ڱc111 SCT.y]˳5#GzjFS~ =zP?NNN^_^{}Ϝ8ˆ?ܷMo!&* Qd!ell̬YXx1??fM~DEEk.bbb5k}GDôzj}QڷogΜaӦM24?XA͚5kh֬Pzɼ\zUv1sL?޼+xxx#СC\\\ _~ܼB?qcǎEXXXpi^~e| 6N:ȹsشifffLVVVbccqssSU.--%,,lqqq)lprr㵅sOHHڵkksssqww'33ckkK+ ݝ;֭[kE\\5R?33R2bwryiӦ:all?BPKLL ^vxqss**9-N<BJ%bɤ$MFWW3l*E\5L /ΥsGuQF1oە>R!|f#F="UO兩؈T,>o GٹgLz歚5(V_[q 999XX 8|7='Vdg0wqů7&*tѻS\TL^nV6VlɁDz^=oud!gll̈#4J!ĽTߩ\z7|th([Rfڴi%ow;f @F`ښQӃ[|~~e]3^Zly}*7jԈFU?J$"IY7h;37*8[e.EZN"7U-:::(8x g w9ʼō83kkmY?\498HJHf_կ--h}tuOGF}粚}5}>^wqexzTlrֶ<def $'ѫO $u<BQ1q{ѵkr?C&MD׮]իڵˋٳgkBTHnQ6GbWMO  #+|ɳ ˦&MINu@оs[&ЊUD C#C<]qtTYw_~_n,.:ğG̹3e|:v){T*kdfcqrqϠHK`+))aZFER|}&9.TI!vB)^O|'!!!;w|+!jP !CNOOW[DiQ! A[K8ʍ(:{H0݀e{/7'&&L2㣇+o-v'|IKT;({׾P8˼1m<,_I[Ej:J ֤yctttx2N/]cwѴEL^M닑9 Q/BEVP*$&&o>N>ͻ[-&,(&R%ĬX"Rcjh̹.^b``@ߎ$/7NKjge,LM ƒy+P*HLH1iwP|%~^]Yw<[{[<=Х|kkFMxA˝!L{>8|こ3Z6}:Hj!\r={p P*UbkkK6m1bDNc Ova&SΠTbfhAf~:m݃0,Iuo+.*&5% K+K,,͵rtLL137ɩci}73P*;U2Y)*,ѾRԡIFBиqc7nnQoq!yt Т *.-"RNrvMHM MCJ՗ rٱB@qpv B!CT*ի~biY 6mʨQXիWsanܸA=o6mݻ77o.ĉm}}={kѣ+uN8Avjl}Je˖ :~FQ$XΥ3F)[/}En2zan(륅Kj!g}ۉiӦѺu )))mۖG};r>ս xb^z}?s|}}mĈ;w[[[333!<(/_cKk$’"ΓBcK\-_Xu dH@-iѢK.eٲewɓdffҮ];~I&|'7u0*cǎaooO6m*ܷ7o@ǎ P(S쌱1zW^FOO Hӹqzv]tx5jT.OLLJ%((333K.w~ nݺE퓐 J'Nhɓ'ɡExxxTFo*،D_ڗӽW[79p7+kBLj!3<üyxqvvvM 1L0%KL{{{sY|-[oOQQ/+WҪU+ y駉u&U2[!DӢE .(([Ĕ?ի8x vaffI@߉RRRhѢSz뭷(..ѣmۖ=zܱ/aaaرOOO VS-w~([}v\{gry}Yon߾z?L>}4FKKKٶmxyy=EEEٳpYoҥ NN!<~8FFFnZ oNzz:={TV믿ҵkW:⯿"%%M2poڑKDy̜th}),)la h}]I#ĽI@-Bڗz>CmwET9{efr1 Je)MbmbW29x+_7e<wG{GzB!V'9;[CŒeFs5-]: 륅uB!Ŀ,ZH]Q">: 8[xg z;Vb2dΑZ!VQ\\\5BMiiz}\J9?~vM}iBQ%P !B;.bRڸambWndFN+N؛9k$B!KT} ܭ}wCz)NL daZ!BBE|u"p@ fAI>gC150BG !B2ӹr]]=:xȺmfx/|eZ!!VXR@DysStlW{#/EK !. B!B*،D_ڗe:Rb)ndKK !6 B!2y)\J9B03v J8SC !DZ!!_Ǖ0 2hGsjkKcXۗ*Bj!BNR~،Hli]jk?6#Kr錝/W!jB! XjNS°4!Ȼ&ֶRUJx) 33m_B* B!ܢl.%$.3ޑ<$)륅' B!Re /]lѩs^:@m_BhB! DbV,3s"gF~ۥdBJRiB!efr1 Je)MbmbWg-ںu Xff&ӧOP~!uP !BSťED*IΎ߾>PӻzP -nȬ ٳ$%%ammMPPBAKB!Bhn>`f^*GbjE+L?$ BFF 2D]Nj!Bz$3?K)gգG,k\1WNL+՞%\mՋ?ݻw!B!D=PXR@DysStlWTUJxIrշZkWcС{8&'Άӧ ~Z ^d3Xw)vm[vҷ`"#G]xb ӻXyoU&#B!ըWKZC^qgcelCgg-ױםlWllm(**~O_5e6o];k/bae @~~SΔxb @֭lk݃#ׯY/zӭwHU`niF232),(R2T*I`ckw$B!D5PTf\%*2־tnR&s>8iH۷E<ɰCA!O\Ѽ89IDAT}md3#ܭ:ppg]115QF``a?>]dsPTT oWokp9,,-hծCG7s(RԖ>$u<B!BcDBgZj%N̅q `q%͂^W=?_n\+hն]rmԄE0yyt{wGR7o݌w.>v]0eߩ?QӾS;m]GED'ؼGE֭,6~c?1>/?mú QdZ!ꩽ{g5 !@__ƍG'8+addĩ5nZRe NWKhe1oFp#ΖD'ޮRD?Yuuu)))Ԧ+n2Ӿs;>C ;;tՕļ75|#]*&00q@,,WoCv08rg_w߶wF~d4n<H@-pƍ#00Z… 6mM6*%闉͈ƟVNlt(V&vtvҵTYJlU߼ A}110#?Zwqu&F{qXmz۶`e#}cim Seg2a:/̫{fdlHqqI&77GNihU!qr 'Od޼y4o\i!@__={2uTV^M|||ԜIv-ȾւXEn2GciO L0JIlF$UIg޴p鈉YW}EmNHvoCZJЋ+#8y銛@Y9PFMdؽ;z-4vk\m[6I_䕙 TcAB3{aСU8!f͚1h ~O^rr\δbSckJTendDֽ+6&ZKCRHuk闰0G,k|c[xW2b>AZ1ϏMV<1f$OАиl #Mecpp}ɺU<^'Ҥy t]׮kPKoh_Ξ 0.~[cW7lUn StD~=yf%Ƽ0C#C>hӾUw!BQW!!ݻ/Up-5&]OI'((#Ȼ/F^F%e R)]`mbWa͆9y4M2g[9w:]{vC'όY6$еG}b;뾟cvN>]K@r}qvqb 5H=<(0669Չg{ن5w럿`7? |?P^oT؄dBze̘1|I!*BT2n8JKDy̜thV%(3 XԩLA)9 D]@OWؙ޿Q ް?siϿ΁3ݕ;7}6nܨnBF)--`ZJեRdfr1 Je)m܂jeT~r8xxXi; "7iP$С%Z!KT} ܭ}A{ӻoJč(Y/]2\M@aIqrk _/~\VH@-B ׉T\ƒn>13v^8%y5 i)߾9V^EOOe]{*۵v7H~>I@-BԐǏf /YdV^U… 2d[vW*,3?K)gի͕[ؘ͙ʵf9EYD}SYS{l@Fz&vھ|8SL ""e˖ O<>VZbĉի`Xp!_}7OW_UpB D۶mq?]v壏>"//c2r l]{ｧ~ҥK?e ={dXXXoܹsXXX0eQ[{n8vzbر@C+Wr!lmm4iݺu8]0ܸq%KpU}Q 4{qy<==-O055%//+W_aggǤIp|111SO1x¥3+3CnotQIFED_&u<;7nܘN;xlP<QھҒRcSرO:wLƍ%рH@- \QQ /78;; }Q>;Fpp0Rɾ}P4h^^^,_x^z%֬YCHHL:U#JKK8p >>>X8^|E uP}EN>͕+W4iÆ ST*ٳ={6/KKKJKK0`|ܸq^xꮣÇWБݻW#ޱc͛7m۶ܼyw}GyiӦҒgȸq〲 ˖-+P⋜={yͷ~ݻ1bJ7xC2j(N>͠Ap^^^x{{#p):vСCpu-+T\\L>}hݺ5+W$::cCRRz*xBAPPcƌa9r3gΨST 0gywyh^{5 )**wtЁ+W3|͖-[ի=02l 2hGsrUҡؘ8ƵKL?~snd^қ1ԫQcDzw^q'T*mߊ 0>}h;Z!|&OLFtƶ{{{TVZqU.]"0p@q^^^̚5 (=NKKc޽дiS.\NHH={DTJpp0lڴp7od߾};صkgϞSJpssۛ=zo߾, ttthҤ /k@@zzzﯙ7nTp֭P@miiǝ˗/abccqpp`ٲe@Yjaag„ 5~R>ltmΜ9|y077חk_ӬY3-Z@ΝٴiT._aƌ?G}>bb"_~%:u}PYt?qVaq޽{#>>f͂1222~SSx?+--kccc/tgP(*[9p֮] J h4׷ ddd@.s܆ зoVgff"::]\\憽{"..?BCCuP(Z]f8p/_#** 3fz&l s:C2W/st ZTrE&d]K?=9s?d2ϟ9ڵkܰa`mm}w2  6;sL,[ شi>CqL&q~Էo_PT_+IIIdmۆs{1dee]oKJJğmllSOaɒ%hnnƠA}=233ugee]hnnƌpTWWL"vŋ(++kիWdٳo^9s%%%ׯGffy8t}'HLL9F*Bш]uÆ ׿y_rpsspcVC}cc#`ԩ8y$+، (JofۑF 񼆆ر| :nTl߾]ܖ M6AV<BBBPUUծUիjq<̍-1g$ô(_.BCS1P=,--uޖ/APP螼sN̝;o-N"&H'[o%eGJJ k/b:w\ٳGgr/ppp_B&s vvvmvvttDnn."## \$%%SRResYXX@RA.c(,,o&N6|pEY]1N\9sܢ8Jj k~T =c`od貈28 %!!Ag,24L0ņ.Kڳgl٢:33aaa]9^?=_Cv$[$"7CMDDttJJJP]] 899=ީaZj+ jTPK֪7[{o0P O=qu; pttĸqO?NScp됻nrTuF3$]03gj&"5FDlݺS[VWŵS ^{omFRJ^D% 5F&LDtkeee:wle:{K߅zU-rP 1i"0P( DP(ęOE nFurg~Nwc JD]#"zbݨ7t)D]^}}=vލ~:U R\_=T&\(=caflqpe&P=lB^xAAA.Q͛gy^% O{?C~֨p"V^0367tYDDwuA8p\OX3]Ges(- }]ZYR ]`abi貈@MDDDi'Ѷ w[W*Wk7e3j"""T\3E=]{s}6W/#Gy.euj"""PZ[/}W_A26fvF!@MDDDd za@lõګ.Opt1tIDD 5/}Z=sF[(+%F Xk7CDDtq?""2/(((kנj ]=d\\\ 1m4xyyN]s5!R eT~m x$"N7DDԩA֭[qIL4 pssD"1tiQ*HKKÎ;xbBuIm!2JN7<| }K]JUu\R*Фn@K8| ]Qc&"NuA`ɒ%9tڵ Xpax6WRto퉨bo""Tǜ9s :lj犏C+h1/^Ule:*>C 1b"SeP7v[\3EBf0߼6둣@Y5ȝ c""Si4/y$ 4+3/?-ȹ~%5W 0,".()@Y8$RkTȽp 0563tYDD]5u[j i!@GuplѪWyc|M, ]Q@MDDDRms5 m/jp*.baijm貈466?T*B磶\\{y˗GvkR#??jZv.]0;vз.jdK#ڻ[iŕlj0w"ܣ5uix7ş bbb}1x` Xx1ZZZ:ÐJhhhh8Dgggt|lL:Usѿ9raaaHIIv$ .駟r+dGV9DΧSەª^(K;=Х=p囈4D~-^m|0`^'|UUUXn]{c6h _~<\vMW\ٳg݋z %%%07oˁw%%%xk5V =%=4V3f-`Μ9pssx 477Xooo$''O?EEEj5r9cmۆ^zIyعs'bbbQF!//|{ϩSZuVDGGغu… HLL/ [XX#G_ӧkj; Q^^f&L@cc+++1{ld2w>d;w\W(2e ЧO?#Gb6z%_PPc" HHH@ff]9쐚=ۅҺ"#:5uy3gĎ;pʕV܌|ŋxWl+$$RΝ Yeeeظq# !44}۶m8|0> ccc455߰a.]ף?.\Ibcٲe777$''_Fxxx}ĩSPPPPlTR-M%=ꫯ"88'Ovvv6???j2PT*= ]N^6")) 0`RvYYZZZt(@tt4T*'M &022+sr9quccc-,,tz> 3gDdd$VZ{~J\*WNU pxv7DDX`6m$nCee%JKK!"meef۶mR)"##!$ mΝm%^̙3:駟_vލÇcnn~qƍuzY=0bĈVr9JJJPYY GGG@FFǧxkm񈏏GKK V^3f5aVAvy:*t EPqdW^'ğ1}t̚5 .\@ZZy,\Pg3gxk>$ zիWHNNW_}|N>g⥗^af;U=w!??'Ol=-^ .ķ~|=zO?8D"Azz:JJJo>qYYY矑'N@-´ipq(J/hWm~~~/̐_|QOɓ8y$#((Hܟŋ#>>SN_|?:5?>0m4$%% #""}i5fzʔ) 6`͚5s[{شiƌ۷/i[nG}*tRr,_J?xnll[bժUx`mms9O<T׹gTjl///|Xf 8::bɒ%ذaV^ V(l߾=Z@im!|0?& "">Z®,22k֬AllK{޵Ei(΃CB`DD] $"""5*.*v~?f0j""X|9 ]uSm +/!d7V0uj""TPշ\+4iK{htzh- *sp"V2  k3[CEDD@MDD]{# - 󐣼{KG[s{CEDDm`&"N5x`߿:B˸- <Vf65N.QC~~>kRݻ,%5o? *s1 DD.EDD+WƎfL5=j5yfDDDg1tI_Cv$%]b&""hjjž={p z 3fQPK֪7[/CDDDzb&"""MT@ApF.'%#"""jT.Ȉ= >W"G w @H* DDDDQ݀(-S0a,a@"5QPiDqM>|!w 1g'"z1PQΝ;qYTTT\\\ 1m4xyݿ.W\ժ\xf憾}"" DDadDEEaD1dJiiiرc/^᡺Eۂ,\̆ .a04mQ'b&"i&`֬Y.Hk.b…ҞVJe6*b@0X6ڀ:ٳg1fCAcС˻vA݃ DD/ DD$"SUU777CAz/@@qd+acf~^`gh"".:V !Hh:ZUdhb!".OqI$5{^Qk DDDDs CmA42OCDDD]5Q;TUU2 ?{`eee2Tx 4w;CDDDj""2*aذa|h4sĉCll,\\7ȑ#xgjQPPfuCXXJ%n݊P:gϞd ޾3<歷ºuPTT[[[C mFs(<0222tYDD`&""8{,F-[`̙d>hW>6l؀'xxWwaȐ!w{vZ888vCUV Ρ9#&JDDw &44+V@|| A0zh駟B.cƍXr 6~`ƌ3f &Mq?O,]k׮EHHƍ_~Yܿj*DEEa޼y5jF#GУG̘1FɓuELL Yf!00?3`ϱb $@zz^^^Qrr2"""/cXj #G"$$zYژ#4R 1ܓa@DDA}C'T*aɒ%k& \pA222Az_~¿/]ӧyfAR_. m/[oqu|:/^(^3glLLL5k F=zb f͚%ZUeeeT*?.n{煥K?_|Qhll9_BVV\ZZ*HRĉ VfϞ- Ztt ]'--MviQA0a͂ BLMM?XAhii*>ϻw4AҬDDD.DDd0jшM S?bcc œ9se̝;\$''cŊX|9vڅ={bϞ=Gnn.rss}N? D"7w{n8;;#++ YYY''V`:&N3f 11111:wT/ŋ?qouس0i$q:;;;/31o<1 g9x{^dODD7u.V\3Tfiis"33C `mm-$ ?fffHLL4}]V[ZZ*LbժUSO=pdffomm-_]] gg6۾W555>_''VϏ3 5\>}}!::%K@шj9rDKV…  Ž;Cuu5`ccoNrue'[[[TUU޿Y-{斖9#Gի1{l[׿Я_?|xaiiH\|.]Bppp꿓޽{cݺuA\ꏟ/уe˖wb2e ><HHHswرcBqGQRR>7nDGGcҤI5j,X`Ĉ8qx][[[ III3f 0y;[[[kacʔ)իWGŬY;;;c>%$$`ƍxԩS8|-&""ꪌ-[EaΝx'}#2 B@@f'|7fgT*qi'N"==Cc=֪s\\Ґpq\/ C9GRCгgOq)++VEr7 ő#Gp5 $$cA&!55.\1qD.xyygϞ;␑Coƍ'3ydHR#F ..Nl?&& ٳg,X@ upp0qQ"00=zЩ6664hӧOGmm-;_1666:kw=F""/eM""8)@MDDeDDD:L&CYY QVV&NGDDԑBP " .B DDabcc{n"@}}=vލXCBDD!j""0!!!߿?-[lCCݘZFzz:-[k{u$CMDD8p ͐! 3f!"5囈H DDDDDDDz`&""""""5@MDDDDDDj"""""""=0P遁H DDDDDDDz`&""""""5@MDDDDDDj"""""""=0P遁H DDDDDDDz`&""""""5@MDDDDDDj"""""""=0P遁H DDDDDDDz`&""""""5@MDDDDDDj"""""""=0P遁H DDDDDDDz`&""""""5_KʮM%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00nXt<{ gqF2(`cEgcp}S/_$ 5k 1̤wu{zzpM77?y}} {άx2``ڽ=OСCX>a꥗^_Y';u]4 O>$V+j<شic8qƤQhmm_Y3<{"W^y%֭[7~+8x aqYgkrwu1ܹȒN D7nsرcx'q1s97tK[Dm`o0я~`0;v\?vgcƍSo< (nᆘ3xQTT.ho&6mڄNx<lذ{}}=:>غu+6mߏUVntNgg'@8q饗N'@}}=TUEMM nU?p=f3@u<X,k&7sزe q;}]L&\y啸+6W^yÓxI{{;y:tP]]믿K,rlkk+6mڄcǎ pW'<ݻ5q57''6l9={GGG`z/c325l `l2&`ϑCf} [n]/2W\)X`===}s .zo[?=}c6m~)`wyc~i&Bcݻ'<4M2L)Ǯ\;v7dOIf{(Xy'3[laXuuu#LyG?Qۊ+|߮:=1='?0c$z_v}ϔsI?n97|s̟K/);sG?>OLyN4_~yH$)aLz| +%\2|ys3쩧=Yfwwwx'? 3LS=Ó\tEx~8qwy'p"7+;;.WO=҂ÁqF躞ύZcm!`,xo7zV^=7;QXX'|ro|M74)[o<1? &-3p-ǥ^wy>w~<#Vxgpwwq= ?EQ|D8 {b`ݻ_=~?~_p-رcw<֬Y y͛7x ;`Ŋ?!)?^{r@? }]|#Aoo~?6n܈g}GE pma׮]1wy?/8e\q3믿a477n͛/}))ټHuĖN\wkfu}[q? ]w.lFgǓf,3YYoooq$24G?Ygt]gVb O(Ӿކ yϿ+ [g Le8k`/BB {2VGlOد:b0E"k.v2믟ts8Le05f&βAp8d`pv=h욳zj0|>ߔ10I~)> ;sׯ_S~~B3L1v뭷2k_ڤ;a}IϽk [tlDf&ul6&1^st?~3?c߹s'S]]A` }& ff!\ n:1Fo%rq@^?`FxGYYٔ1Nsҟgʷ:3o?ߏ~?a#w$D(>Ci!X >XA|yybe(=:^Od23qwLzpWrLfXp7^twoG|K_2SoOjs%999F ۋ-[nsܔ7n8`d;~pc]tp1=zt^O,/6l؀O?=1^s%I;)?niغuf^}؄C$aF~Ɩϕ,(//xuu5'-&#.W_o~477Hds-F7ߊ8qH$>o>CRK)z_~ ł . $IذaxB[___FSopM7`$G$I'?oS~NKK m5*02ǶmPUUk\p?8nv 3+Ʈɪdɒ)u8CUUqa,[l^өq<šCUU'3kw!濁{izM#;p<` ':r0 <uzVן'|s(q7rݴiEIʸqi?T#C_;>k^,BumJJJ&/{gqFxسg `~z矇o6\s5Sc{ioPnynN5V;?|> i=N;)``ӟbɾx\s/=v;zTWW<hjj5w컹e19u)P8qup`$0X4 Pg;ĺ#Ω3- 16%hDmC%L8ƿCeS::: ٜn\?OS`=mQ("amϺJʤkwq~[֤-c߷;~MAp-׿5yvm}ǖZx㍘KINN~{}yfq7⋓רf_sgϺ=^s8/JJJ;t.5|ǧ-7()JK9F`ςAs9ǶmW]uդNiڌ"H%i}3j4v޷ocAx^y1(7cStw${s#3*ǡ; :g5Zդ;O<v5\ow˩||&T^ 5k_*vڅj?~|ҿt[o6 \r,bLtj͹S8qbJn5y gsN0puM 4Mg<;[tLك l4 X䩧 UTƃ&硏0"oG(¥^:|II L)3:-CMs?^}U8"1ҥKK5k`ŊhkkOOu񪯯5!plۓjXV<8ydccaWh)DiOaMx}{t8җ?s񫮺 6 O>7=}9W^c=x1g/ƒO얌t7?Vuěxꩧ}Ӄ/| FOMz.--3[^+۾};Z[[QVV6 Dyͽꪫ`Z+ j5w=5^sǾ{V%}Kz^Z4vh2q#e,L:gͲ̺^rloYY~߰/}KtcKK˔~O|Y__{ꩧXII lӖ8930EQٕW^96[F3׿u /M6I Gw2۞{9qX,췿cǎ'_>?cW_}UWW3_W1K$/~lΝlΝSO˗~uuup8ٯkrJm۶yM,OX?ig ;v4 ﾛqNJY4tΎ;$If7ȑ#,GGy]~;Μ }c=>O_79`_~9;pdXaae8cUUUlǎLugzj?vGe,3n/M6MR=ZSSwyg'NLy裏2TUe _?~ɓ'$IL$p80{衇XNNg7wÌ8fZ~;[o;wNcGv[A6<<}]}/fɁtAc>jL;k1-5SZ쳟c^/[|s8cw}OϞKm۶)x?L:㪨?~p8bSj[ bLLѪ1cc?x̟uj :2fخ]GWK^ʞ-c_=Z?L|LǤ:?-V`c?pZe쪫ҥKgs<XS`l֭1{bV{{gN7cөy<vwNg5rM:l6G}tƀisύYQ}#&]_zr-nmmYYٔuy1kDZx`կqS./niƀԟw0=mo8JhK ];XfCGsIX,(,,i7DCCCӟ 777n l6q Ӄ^{ v}J 1}}}غu+8Í78i۳>p8\psشiN8ݎ2\r%8sb;8lZ[[e8p===}hN>O=vχ"ꫯsoݎʚ8q{/:::PVVn ˖-K矏=׿bΝlذaۋ;v;8;8Nxc;gy먮ƍ7ڹsNK8v<\|x뭷ގK.dƿ߿`Kn޽x2^Dž^;)`:Em#ԧP$>q f D3&0oTԼ`{_3^ 󦔌m*B Bg ePF`'\r@$I#Aݞꏂ$d0҉Ql5tx>Dp9Yp!/Tb#Le %c:j"kp #M',ñv-+ՓK0}%H v);*.E|.!$})H#)< t›Lp[LR&P Bk n6<"9a~Z<3#+H9q n& !G*Tb%^ڵMIc #(`"3b`Pd"-CpX<ϣRj%Zr%H TD5kK ?OFPD3 }VQ>q,FDL ΄TV!SBp['7LL9R>``ӉtQ[ Ĥ1fY s0vef'(E1ѣ<9."YaT6:gt|0VEqvT 4 %p<1 j{LLգ8kFXMKps27%5%:IYf*HsrL ^LEEPxPhnmz7H}qLGϗp`nF 1ji*hty."glVTZ [uuFڣ)M#ZK>c*`9rl4MH4}(HXf"p<\B] VVm5 2LP- E|8ؤ9'ME(Ҕ7! %-L8&kUee~i =xBoI0.{x>R ֪TBt)i .>/-7P.yX-(o#-Q!#= tZK`=0͡R y{#d:%HThh/qXS5?L/܎qhFKp)̼v0xŖep+HIKpƉT@LN`[ODSc'| vZK#/)y pR LtF0}AJ *|J?j+Y0%j8΋"lWCrR6LiP -MtjMq*5$$[誊}P&=h + &ь10E : !Qtտh-9I0!&\~@E,*EHU!\Y+N]^`[ݞ귑r0MD`?|j? "j(C"969f>'ұ.DdqB!޻JEs9YsZVc-XLiD#h7% d찉.p?_@eT:EHU]r* ˛Lp[ m~!$)<%2TCA . glyM˃m*C52 Sw Qp`wKEit#y0}P#2! # !z1P4cXCGF L h:/Ty1b`D06?|]c2!qB!Рb(҃2DJiN4 +=ЙjHW-? @(Ki2&Ia I!Ub(ҍPB.!Ҽ^롆BPݔAѠ tt ښ1(iE0kДf ~U*_2hSt/<ϣز nSQJHLc)u%J2(HpIqmPZUsYYƼiwn0}jr/O_}%l*I1^ !(h" pȧ|x*`"$z4 SN"d\Ƃ^`[=g)` 55%ʩW1$[W@`4!.ޒYұbV1J 0P!o--R!a=,ùv-kΊSd4 33Buܳm+zXΕ0[!!2"^ mӆ|׋w "rDdu͙9+NZ(^Co^/nFJm4QU|oM{xN 2Ytpo%899|HGXXy(`JPt`C%nVp.ݕS$L N9 V%w ⢋.m_(ṿ8*<%@=ڵ̚)6 -pk :pw.IAy pHHݞKG}UE2Ч?iΚ.8 gIH8.o,Vr:a_9t+a74XFj~‹Q~*s~M=4]P~u : IH߼3M="Әht(W^uXicݳl:|^`/ I3!ŏHT?|=c0V̮a?k}xFҔδѠfepb[MG~zJD0z(?8MԣRXl(:8Q=R#KgGPR!HKTE10ws`kS=TcPXfj(R &r|۶ p2y;:o\2c%Iv3rLy(۔}]IrT/nF Q6ap0pӗz$͉Tsq1,˖uDKr1::Ki,G9,c?߂T!E c t-FzS=ft;xGO ` fUZMX{w!В(]ۻ J@ՖøbyaCҔ˨u_$C!)3VO =xEQ!I#ur{^l'8+KSVH368%UU0mLA3LM~M[Z O'ʊ":ó/Bq9$S1' ܌1hfI7YSC۶AzS=9˃S ;WB T1aU/d ^wp$yZM(DmnŹpxx4Y)zA24l6ȿ\c Gݾ}+wϧ\H2~a'ܥNx(h"S1Ճ0= gN{2Y` tAzIj[T^ٌb D pD@߹`67]:| קr|ͅdS/ {t1#SLGx>X$!$27h?+`u7 ]9K;EO%YQICb͋*`bwA RV~i'f*nIbҙę0@Ue$4-QtAcPgO6*?/Ee9xݰpʋR1tŀę b:~n7xLU,I1曈c1TR(qPlw੗vBr(^Bwd*]W@̛|+CN1"=h C@)GsJN'׉27~y'8EҲT$M1Q,s0]Grn.x)5קE0E1#C`3OU@q%4]cL "3UVlR B{rw"m.+j^Ɩ bxN۳Bp(XƵSдXEqIJZMf:C-zBNDCaM(2/L&`ì+#&e`ޝ;͈uL -U_<jhBT$/ &T9ODj! _CKD#W'ZqM4%לRUU0%uL0E0k㧯6~.fJE"K|GEcc KH״JzІ0Q?I#nc<òlLE+9c> c#P(գZHwmyR+6~lr!/)DGA!5i`Peߨ/m9iJrDd<ò|9L)"܌#h'ܼ( ~&#o\m*s~) vZit >i{.K\ILsr|H r%dw㯕 g'N@p &(k&0Aw98%d>yI9U,&!͏aUߴ0UEDM⇯IL<\r=^a]5qu {7]].4MݯnBЦo^.f.`_Ke*Dm~e2tG:<1cϬlKNt寛*W@:C8.INa4~Lۀ)ՅݻQ Mt14f;o1غ,o34?:|3݉Йu+A|+a}٘d24^`_X"yL1O7$s:~u3$~ H4e Y0)Ye ,KRvBJep7{{EXRZ40 W;x%j-Xn ܳƯt^Dʷse(.E62!(zZu`LMؾ > QUAA98D7k/X1&01nm>(b̞=ڂ}bWz8YxE) 8N@%Y|WU[UCthכg؏7653W]r d!G@Fvp&쵵[|LL8pcZK x0…XNyqp q _<,Pf]s*t#t %w/eI3/Cͺ~.$4ڣmaR[* Ezj'8a/T2Axx8ň7PYNȢKk!S01MC!Dz{;/I{G$jj|`ժ|b;--x`n\3N .pAj- |sٙQt`8ڗɺZ0da;؆}7眶ɋ6ooHp<jzYN:f:g&:Hmm:4kbp@X|mX12<R @QU4wuP7Tχ]mmxĉI*JOF.-;۟h[/5z8i"8aoK(-[ݜ!UD ㄯ3Ơ CphiY!>cK!l)&ʊ"hGE&C~xuÇno;f`RZ\8{z648,͍oﾋ܉@4 ٌ-9F>^/V`uQGz{MR8|s=xzhJ-OaK.yQ ʺr1 E؏fh.u(}~C㰢&xe7WEIJq6`fci ' \2ʄS*w+K`0)VM~>ꊊ20`UrNͲ2:^ B*6:'1 efvY8jR>}}XWV꼼O bɺ_6 )nNJ|Pl]bkռEc &;BNmNBÆxa^X^Y!Xu$XeE*lp ;``NT,I[.,[| GV+)^a|ۏ`(Ouݶ6,xP.09k={Fqi>uػO44DI͆yxfn!,]/f/-;\T`\~8ohV[FIڵ͂ExqKzQ[%3Њ`K= f9JZW@ٖ/h6^%Sr!oɹΆ ȳVU{uYpmy!nQd]Jڤu+HLX`_p_dp$tξn M_YW N G5c8L G)% F_6٥`4MϪƷ/]:,=tQa_2JH|^7ːoTuDzzdsl6xt$( ~YT9NKʬD V+uugĜ CK?~iv\| 2{MIu]Ǿr-嚔0UI<rmSH5 {|Lcl1s:Wiq\ 2.Sjr΄SΛeR䚧Pz{btXqD {zkCN,PWrxE֥r%Dիvpļ֬+ c~ x;[[VK ~j\9~ޱ~UyyN5r(Kw0sx ${7vvBg 9-& ߼rij":`uȬR-l+8Cuh(]L2jg?A?}Q䄺Olf.`yi8Tt:a_Dn^ :󸪶~ "?۱܉.׮ )?XY8}}%;Ny|,.8h9ԕ,`e VdcjI$mȬYpʞX*.]l@ўJ&[F^%??AAS*56'H["k*朶.l+WKp7 04'߱gaukK/ͧkVGO??*l0ubcdB儥<it)`iXG)Am6g#Պ|ob&"P-$AƒY쫫,ǣܶҰ Шa5݀~-= tMMN,/`rBuee2CUǓp%"qiM 551͇xR$o a(BׄUT{{! ”YT)ٌ^q%A<AT~xG˜gAJu.@g?*\WWۄ]}3.k{lJ=gy(^ڿ 6<؁GwF}Gnjwg*$?.n@#?;@ fjg&Rv2ûw/To1^Q, d/_ 0< (M &?6'cJڔMjIaKE '{<\|fWƷ/[4pfχn?mߎG}g'9yMluUšnxaxܖL^q%!Ev1 .H&%ZXYDzz௯NE ad'p %MrV>q<2jyrR*%˒%0'!.؛.t:n=wc '8 PWa5N8g7܀_x#w啨p?fSKo/ODTӰC5P(!eN(otk8X!'t߇7SɄX{J7L6qc58Ĩ>:[umm-Ϋ'UOqQb6yY00 p1ߺbr"~&(i4D%4YZGJ uCBx'zJ#/!]s[E+ |ұӼ\%8mr :o>&_qʲbP"ƂϤ™QE*L9/otg:boE|!~62GdN<t=rUK$HpH͞g.R2Ѐn̪p~}.I|c"w |ex}T)#qn+E`WFҹӼVqۊŨC?yԌr!q'6r|sÒTVBCenu~ wfm1~[\,UE&wingyY} 1etriM ~~unMӴcs7f5}Riv4wue૗\'qFy9>}`^ܿy㧛6M)ap*bvS睏3&X,] oCXhmŧ9gJ=\Hx[Ga LRKvYH̛hUq1iW=(/%L[&`N9xr^fc)4N3t>nK* K ϼ K =p,\׊T,ԕ`"IUŝ Ϋyu}RC߱3c\~#)`w7^hnѼU^55iOI=/\I8;<^Df'Ip@[!(㤵 QNM!ij! <}b2--ϟ,ZPbɺN)aj8 mP3KΪypL*.]l|&*4ne0ĺҘ94Cls3ܰfSq(jL(sˎQjvtݶ6).`ڲBó/Dq9r< lZEUJG @x=`լJ!J|0;e<.8ɾzlYX<#W.A}Lbv*M if3lj"i Ng:,cY~>ΫlW@O $eN2%(xdHqxҩhhp8Y3D68?nusYlrpIKN t]7ƃ;wfl9|s9O?Kr{&"N4^@e##8QvjA@ad)-΅%GS/bFQA#74zq=vT8Vm*i0hE(3״L&hEy]^IjoG!<܌&H5vvV.*IBxO?}*qVݲT"A@SvjM R^i36M&N'8.&6 VWO~v'?7h`ǃ<[fc@ʄ;w]ױoGsX`h.46>qY/ E)I ,[v#ce?M#2rxd(.ħWpz5͆f̪Hz,uy#SYU #"|xEygN`f$w.YT .`˒%` ^`ZbzcF==^{T Fkݸ&;ׇ]g=gTT?ۋ #}NUDm't}Ux^M_VeAsG%˖#g1+mh+ OGa~ó{bOGzB!0spOgNV1 gW4ҷ,'{q[p^MT H[ؤXkDQ]yjk!N QrzBU~>}8{TC^;r1\bn?I7/64<_ 8\5 4Y8$,K4sOܞ$ onwv0(.E}-KH%xQ}l6H0E:e: .@TQ:\)KxQE>H3$wiS^>;n]Qߑg/ .]:2s=Z#ǡ T g/ۆQ| msPjYd `e5k cW\."'Kz<Ϗp`OMÊH9K`8<5M+vyٰl(..=ܓ8֚cb@a0fgף}~CK/ȺUu, #rNBCSN R4D2P Ox>q3F |47@ttz"~'$ pߟ6aY]}_p&&jV)e122`5@1fФ BQe&y wrxSQuu&Ԏ"d 4t2 ]q҃(8xA6ǯMN)`I$7hVW>R>% >Z/P>qNX,)X":g?yGQ(t2=͊?% ᾧ&<;$.,LME,% cgƨ^/MMShhnZhuk 2S @˃p^WImEP4AE ?ƽ܄"KzC)t@/oDJd|Oi AzS=|x'fj `S[$ʪ "=:1Ű.[=IG O 2@AkM:thÊҥgX\u1 mp R=uZ[:~|cўjл _v3WTZYa,|76Nt/ɏ^y o9Mg a%yƽcΪe(VCT;dlYX**`9KU$yؖ-` mjKхH2sxPmv ;(.\ ,)k1}/W o &K!\h^Aa] RݽF!9I}x%c5HS8v7|DA'CzY$7mI3 /0@͝,(X" J.,e2{Bntj|Jb9+ʐguK*KGLjd{<)/HWuAIKvZ8'FqY0P!TZt0 __5*en7r %Ig1@dNDNKN3t>l2Q)g:H΢(&B!E"Ԡ7MnOޟ<,UU0ž1b\T QдT+b8j@M,iaL46B iCTdi75o:ITTPi8'\:KDF- imn20ep0!) 1 %TLkhjpwnDऍr.Day`_zkI>`녿 NhPhq<? ˰4XLQ૯ :?(m) T+ù0<\IQL>yF M4!N)0 5c$~IHzhᰡR SqB.(mrp|הH0Mch.D{zR=E8N'ب %6z$޽#ƊS|) LFAY`*-jJ>(`:E۷CeH!*HI yC&o1ȮؐvCE++a.+K,(`!ֆ7ހFKs8Ȭ wS"jj %Zߏ@S&a IvޑԘ 55T2CP4 }>b^ެHT,cNi+S6Hd&0I"l+WRA B oG%1 RH6c }Ax ,N;~3L35 6!חd4!liEؿX] $yG%8-SAʌC,T7Cݛ 97\qTD8tX8iF7$%8N*H,DNhz(8H99 luu,EO.,e2c'3(YP/$Z 20W_Æ-&$Aˋn$dp[ǎ:Wtt!K"'ss*H%(`chnD:: v<ǁw:)L/҂p{s5AG *i! Rf 9yCFA$ @Ϗ{ R2PK B&EPiʨBpvx..WD i #qereh)A,` ==`e^ &= R"beDव( LZً&77) ^h0hf$do>(Nat{)hJS:HT2+QdD{z*n苤NNgPAJB:PKZ(hKpL a0EAX "H17^`[j,LF&&Tk Ls #]סGdgqNHNgBc)_!z^ HC~'0RҾr%GY(`@K "~Y$HOv%W`aI*HI# 0aH26Kܠc@) Hu5BnYJKb@) z$޽ GL[ bDS~?{qZ mpZ.`6'|ʕtEЂA Մcڏhli/MG)/ Oj `x p*V+DPn*HIS~)9ܰG R.Z0%ա!ûY]. %!z75A7RNz(hi R H ݳLQ{lxQuSh6*9yjS6Yԡ! Ԅӡދx=MPAJ2$tu!pФǔA>_6qrr; %!%ߏʛ肎nD$|n&q Ty߷Ѿ?sJ ꡍeN6*HIHz wu!t& -vO3-TLF<УQxws1DB)q99 %!-ىÆUn,=ʹPAJ2LdADHObss%ļ9dPk+BǏ:7,Fe過,2ٖ\XKM G!P4"=1@p9$ = $$[ZDIkvu. (I&$ӡi1MO]uD{{-@<$6סdPK BB/+ٖ % LLADL2V7%N Sn. sz*HIHb!pДxzm`Zf.PQLQAJ2+ wxpOX& :#sde&$1ųPAJbL LD۳Z4vK G ܤM'SAJB=ɭ4RHm}pxp(Nd.[x K}3 偟aW`6TT`Ir:X%BdmFȅIK,%Si),˗SD  80_-68mBNNNgA) Yܴ`ɽ/x ^(HܹrvsY~QAJ,0S 5EJ Ʒ )/LD) !45M*0㹼.[/Pd,QAJL028@s*>4]t&5T&CNA*\a062"$FSB+sʕu**HI20v '7x*HIL)4 ݻMh<X c>ljKp$(`"]Uhj@)I:`B! Eի!Z%2BrGʣPDRf!G"CtlBX %I-$bo2f y1¶bK$m !9QEs~-*HILBLol(_a\XC0BI 녿 &|.$ !$tL&/˰]KIk0BI)77dmlcZT9Z#tLbDj,A3LBTPkUմKn7uu,!zB!tǩ %@0B7 0]GhATQD!d^Y,T 3$ !BfA ȄB!B!d0B!̂&B!YPD!2 !BfA!B,(`"BLB!c͜%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00dL{:$mdIe%j!%ZH<@ %E<%&.p/~L4AG$[ PDAD$AaNDAD$AaNDAD$AaNDAD$AaNlVP-yg\ʐ+\2OsH B3M/qY*~m-[$Qrw}\Q0f "5Z Tx,~+GU$ڂۡXDڟ+$M7rz}d >:DaDy|PØ&G{V)h_M2 t3MhXDyTVCbIdV:LAhψ"K9B":!_4$p ED7uȲ"Cʕ̊ح !DD7LN^Ir'BA3%fk3<0Mªe~:[jtQ82oJ/,:yru4Su$4k]lqǸ4PQd搇͝!lG)u$ Dcr {NK7}cn{- \3{OEulx*jb%0L*Zb,Ns:HKV>kF2%_╭uza >:YZT-@GieR""FK(SdUhU%@4i LrzM7eغ 8T1%T?08s5́ټ&/p343&)5ZG_`1 3WS8![0$^/`~\Qzk# yS:|PF;f<^bq3=4$غJ4*J WG39e"QJ{:p/*3&p;HkEf-,r'zgǩ=@KS] nDNUUD ' ;[3L[i~$L&W_^%*WA3b#qtle~VN9^Nt1cvvwi07: :GzcK*2[k\_~20Nw#fVؾ> Z 4KH{ٰ"nH0I[C<1Pe,<\e :E1yisM+|V& E9fTaƎ5w1{#>1+E@w*X4QWdSg,{%&,=MA;vh#=Q]+5lv{mZN(F`שC,V)E@i.u+*ߍ"䋥WxyyKSʯӾnհj6SyG&o/V;$I'B(Gz膉Hj~2]7<P0QϭZlK.4NGHdJ -!:x97!/]ϺV;y=4{O#P{!+rjpidKk-rIa-s Kç5^;b ˃wc6EiWU@ns|p:𭛾`SGauhn"?L"SYbgwFQTx ɬw*N; k,o\|sټ;U|.7byPU $9p62irOa}{94ap"ŹI#;xtAt-`Sw<(5Rcly]AP"hɱ/FK7,gMk'J1UM!ꐄi&&p9lؽ ctW✻[;nBMRE[uT2I[mHykI./ @AI$AaNDAD$AaNDAD$AaNDAD$AaNDAD$AaNDAD$AaNDAD$AaNDAD$AaNDAD$AaNDAD$AaNDǭC*H 0?+W77nu8PQDɟ ۶mV#C$A'O/[oq5ˉ"'? ׯIV# D ~5kb! ‚ D0ַx9|‚Z Dv#ԓ]9 F2IӇP?##ް:$a;Ǝ;x뭷~‚Yc1 e0 0 L^/qv( Ik IخE@/P5L'? /?S iuXP6U@l ^)}"iE'6ouSRFޒiaz&i|l}kusvʕG7L|;G?WjeBYTo)? ZqK蛞:)َ~M+b;ɢH ?: ˮߦ_|paUmSAױ]:iCGʦ1]Cy,//busw^?SwyEptJr:[(Vioo:9㏜@^~eebc´ITl蛞صP~Aw4i!L&mmm|_ա‚e yhKME[QNK,H+d3Z0K˿O$aIhDiS1}݂7]^;д;0BV(<$I\pobɮTs4m؆k5!􆶪Ca}"O #`wb;9$޾w? }:5ԓGrHUHr"\/Yμ+nۅiSQ΋X_ܹs|;v[ TK ztMϔ& ]=TDtttX TK 371>EPc:ڭ(GFQ.:%pX TJ ꩏Jw.FR$(歎HU@3#eS[N0ېr3"A*K$)vHҝKAq9!!%"V#pG$g{Wm[:`#-`Y U@Wj,Au ^F:Aa`lkG՟1MqvlAXYi‰+q^*6H5z#&0}uOZnYH[?cp^+(C)~ub}g"hHLX_ )!_Uǡ&F9y\_K󕫋d٥fQy4Pd[PAHR!G~כVZ~YJ}߿bڝx+:W n`LUE!`^n2I>ql}c,;67S[qMbm&fc.Y>.dlN!G5xØstWV_p> EX*guKՑ1w\͑+,%Lv1Z]7)0nTJ[$fmuP1jBhӼ`E!x&ń5#IHk=lɦȤsKcl D~HkI*SQ]DN7Z8T~ږFDvqΡ*C&0?o0(3u9DzÏ2Ù 5P~iws\8ss1s&j՗'ܲa Cir7Sh'©CF0՗(d :'/YM!1|nC }iRYm$ Ȋj:3Lk +8 ORq`#.ߟ32ټQnz i= l6UM.6Y}i-mN69?}`,CW%(ropq==L9d $]*>X5a20F 0)~DFR$מX:Ce[ +||>+qtV6y:6O{鍣`e)?c$H]T' <6`zt`KCq ĦH<ϳjA'٫ cc<*ԩ$)`Bȧ'Bջ蹖ci M(T'(z3I׎7'%~y-F).KsMZ=ƭs- q i7bSieM AhPe&G"F8OXNy+_ ?Cvs#_`8@줛~gWߨjM>CT_t(+HXi%T- MP{ՑAu{:wAZĐd "2i xUxkgѯ\GacgvϨN+(ȶnXE4YZ;$nEzBDMEomEw:  &/ZgT:לkit,f2fzLH@q,NsX7OnldS'Ʈe"y,z|ffڟC]"\8&(Qk]ls/3ѧOƴkV? $'^zPzB$*tHQuL8[[Y,t+7XA^5Qo&Q3)Uas{"-*Q}u ӟ4h&'$\|D$:}]@U,H]A3Tiٱ!w ## ?, YPn_۷cj0 {NEH6Õc%G4M8=J#KǶ~B }"ty~} M Om/fW$ZB:|hHh2$,Su,14 9d Xk5y5+^/z"Aad=xG',>SH9/!) ,3PUs 爧\MQt~X.q},a78ʎ: .t^'1)mڔVz6,k"|"Y 0#6uGb sc4S㱳#Df:e̔4ZG;-fw1yz wXX71YxusG9q9ijYٿhcls;s]AV̜_p=ҥ7:CxbTvvY<#DG XoZ¢3gcpXAΜ_'(0WGx*Cw⸨\qezө|t ]Xesfr3ZZ28¦x*oJ63@|QRxKH\M!fg#xXÂ@ `}$2y-!;Hҹ"FP Z>qb8` ~ g:>Z4Jh.۶D9fptnO A_nryniUܭӶy-7Y]eeW큌hmo\Wӽҏp@"Sh0 -]74x8LUxv] oŋuHe.[:|䉧\K9,(# ykFV/gб)bQ+5\s%Zx";4Ƽvg@YbE+d DvUƳ0&OFܾrli!y4j]sbӌK؃۷cEf(#.pmdĒyqe84켱m$3Uv: ctq<,y ?d`9]˲Txi-w3$&, 4e*&N$(~?mo@[_GܫV5If4D9wTwi=@[}}d :EyispAM_KFKTRaHabb} 'w:B&o Is|4.\{ϥŸ7E Tb< 3;?3D7UOS}ldZc>:g!B۷PjU!,=(u M쁀׌$ACm, R,J,Uh ZƖuä(Ryl9miK CCx7mBvgW!%j|.]>j6y"7ƒdrAc֨d(4iś5kIɕZ{=ck$aLL] C){d }Amjߠ";1s'Bn܈#!~Sxf#X;22]G; K [/=DNKY5|8z+X}}b6%(8Bw;zb4ju8dItj}ouDT3YM,p,1 $w/:-[ppy5Y$IV殺;MMx6o V#Lgu8bMga,Ty˓+ iYp@d.]B۩UWAe76Y OVZЋ/"d[CڵhliٙjʦH쮂é!V< V3 }o3+YWw4q*&$<VɤTNY޽(<ȡCVhCp~EYP6:~8jMM(B[m $^B[̝JͶm$O8y':%<~;Gx] r uC#%86!џ/\ | z<Rk]h7pW2yfbϬsVRُ8:C?!z"qou C,bXjjJI?0gd0ubrL>g1&%;=*'8e7~Ak?c4`~6iYf!cCOh#̍XlX$+VTdzid(LiT f6Oc-w&:&vlEͲ,V/( AD6sCP(3sf<~k8;9+}]uLLLLLLLL)f&&&9)f&&&9)f&&&9)f&&&9)f&&&9)f&&&9)f&&&9)f&&&9)f&7e"2D7:yr& v3*9qoFFfb2 SLD&{],T;7a]F8'Oф()f&Azm9]\ "Ce pXJr5I0: kO@@萯=@Q5z[%:3I\c,H M~Q)^mX3ʑpqP1,F` 1DdhI/SG@Hk1-J"M[n^Lҋ)f+7F 6q-V97 poY9(RnZLҏ)f+`OoIxN%*FђQ7g͌}>b e22`&u\lg Hz̋YV·H RL댆{.zfPBs#N9/ic.[FHDk3$gb< 4]_̛kjGngY,gYy#dQƵ9cM)f+BD 횢(RaZ'cYy#BM)XSV}6bhKc]EAXxF27*X٬7zL1q&"C ;n/BK)7IH,+ u,VqUC0,G t5J!EyOF<ֺ7# яdbĵ6IC]v4F(] vm26SrH<@OHb#O.F$y`(ڱǐUbvj@+xf." %IL{{xن)fM@\eL$VJ  kMcdㅹL/ co#dԸo1ن)fB4C J",3헶vjnA6070*1-z5vP\V6BvEsd |b~zdㅹ,l Rqp0dŋdd%T-Z邎?6N80:`[<R&icV8^47}{ģ*w=Յ2Ñ% R4XJrm03)flg*2jt(@BXG~`#,)W}қUR33gs"tN!fj1&"l< 0bg+Ĵi:NV}FrnYT41-H#^}F~ưb!2BFr^?PxO .f(RnZnN΋H0s/@ظ]Ǡ/t1G؎B XKuCi1S8}uOOtߞd;t'V)hل]qlv =~'-u?Cjw.[7P<@o< t5ظ-ptWO0O7p0&GkU/(QڌC6ѱQtln2qb72ۨYſ|p bt& ÞkB0>:xj{FJpܿ]oZ4JtdW:P8]Dß$<HrKB ʙi vf ё% M4ԯ qqAz/ _2EnANSo̘B\[Y3ů~ dhtRD8}N鷣1IR(ǷPU<'{pڮΤ4%=VAmV$% gf3*d:1/ɩmm52P0B8=5Hjb3vT#Ԕ||G ؜:B;ۍfo{0{ (j} 3=N a$fdhHoF8^|-#>:OȞ<#xGwRXb6H7(;ğS2@eF/x;7fc@փ^SBK)4Dwy4i$-^ h?fzʑ8|[(Vc_E}]UZ1 Ħk0tb Tq"믝d)hBi;w.REb3.Pb_kLȯ_:SВ+/MܼOJݨ5E)ߪH8mS`]9X1k1zmF2'Z8Lll =MA^z8~V7/DDZ!y#rꖱ?` SQ/k-񥗑bRgf76Õa^x#SЖ&3o盟C;|6bt)a(Sl¡d>kƉ/6N"q- NlrtfnGO(={7A#b:_v,~rn j} 'Iqo.gwbƈLPWFxM#:6|3ǸYydӃ^Zdl0v jC1ze,w14%&F2''62ʒ?ᮯmn)h"tϏl4:DX6u})5fTn*ی%aŵ6BL,=!:6ahh~[s/hG/s]fV5`Pl4d} }ƆY0/JTDXP~5f&x6Qct8C<R4u;6K!"j})+e5MHR>y0L̦ ;P[N|r u:3gatl~v]n2 E߼G]l]xA@|m1Z}p㽖 .f3#n}n4׋]7ױi~znWot81p~ak3΂D͓TRqHz%|1{NX׋"Lbb2?=W-W 4ʼn[}*ɾl('^tK U FHE݁V"<'z$Jtt}Dܽ[ ASo)~~]tszlT8ꌾ՛1 Ʀ 2sƓka?y `ᤔDեE<{ b-̍VzRjJkr1d ]׉OMNM}!gS{U i^szln0:q-Ji=g;mLttxF-J!pWy u{Lb㶡{RVϙZO;E,'ff r?pT~!_|b/%FÂ]I͞H YI3_K_"yZ Hlܻ"7C8㩟pP$T˽[ZWfKۇ$JT63+)b OLFx#UwG.gŻvq콝ç/5<mFr>6U.YD|})=5& 54c˞jF2]ӈyL![$VWWC Oz:{^:?t OGsGG]wO]{XvvQ(?5)Qq-FHfZEg6E_Ct]xxv,.sme EyNN^bOJbj3=4)uN~s,'c(|a-T{{_x{ys\?:yh3'_E恝ٳeft_G-M}D ka{aNuP7|,ħP!Qy;yx 4MovpE~V,ijxxkbII72@8c{c yZ/ i(-t32c $EӅٷS_[kċƓݛ)-gyi$Idg򻐫=SROkMX/[U=FO-L':%]Qyp۬o> MәXL啿3,dmA_r[63ۣCؾ%7#\r-2{x7X]AU^>r<'?=hÖwrxV4=y qp g!O$6!>50Z `t(9ό_U&F<ߡP/؋f]xn'kWs]B\by_ lnrO>+t2l'\3}EazG&H&°c !_ŴO*Nt6zY8a *눂CkWuG~x'Vkj[ᵟ|{rIwZ}czm;¬({AF'Y9 %DrމƃkeIn iK~DtQR/yP<3SD+5ֹE BvRUV `jr4N[?;}a_R `s*,ɶN]̓E#KDWgWɹNZ#WgA&gO5VoDB ˼~Fý{V88gxLWqs8g_?ޏùߧgE#_YaKjN%}{=qS̼\`ֽÚ{h2AjE]_+iZtVFs d M''>1ingX=B_CR"d3loH loqnYUqRȜ>fw2aIkp?6NH+-Kalc{31y BS齮M9p.y txy?-uk[݌OVOśhyY]ZȠwןlb;IUi垅>4(pֿƥ4 "?(y/MiK-vָ7k&R-':< XƲgo¡ⅿxNk9ű+MwxmwyiOEq>cS܋Uy%K2sNoPWUFeq>$1pop4οi7-G8huE&JjzHK,*8"|1bk03? X5Y}aqtgUaj~h-Vu*;駶՟:It;l]?b iYEYNWU5pq1.5%R]^m %MC;`MެX5c^\JJ VuIA爥3F?]<#m<}ܸ`;SRXSur"4]Kjs]2 h5"hƽqfΘlAt$x"?|ka,u[WqMnj=}#h}S#lk-+H1DڃZCKkv暠їsD?^\+H.PG|u>*2%ےi~mTpw"ѱQn{zl)}$X%k݋tw&Μf``51x^9ʹs%rc\.y}ں2ݳ<iyxT}g|pm%TV;6ttGo'o M^7ApocK5~hkU@!+<Դ`(/=6{nOŏ$c~$UE]W|SADۚ>Mʲ*hB^GdjjK9K_ѻ4Sk܏8UN-!Z[n,Tk\/o~/  M8ǯ^~Ν7QPwPڃWpEyٹLrkx;ry}_=  tqM9x Q|oIM-ݥK~{7lؕN7z_8m&BG֗ӋЭRnOk-wJj&daeKPItm',~jזSUs<.*w;Q_\.gO_;>_Eyy!kرx\kN DQabfPU&y`Aߴo޶#_ЬuIY\צR<.CдXjpy/AR9l]sƱ:ye+;UO#Qu[ͬ1mwlC{ʾDx_WYI8ra-S1DfHMvQcD#U|x(-*-*uIӔp=[(.qcHsޯi|x] (s7D\s2K oq9|n.^짧g1¶[w_ɞQ~Gݸjk}_}I ߹y'U˸xS\5Yp9mTxPS>oc`$;Nj9ϸi3](r1vV65RmmyODw <;>B~zrrL3LOwՑ•wcwa(츣wSt]p֮+iiZ'Otr|wϝ˿yemI ?ؽ:M#OS5c"U|;(MQ}h. "Nwb1--8QLJEccX) 2IiqDc t=ꐟ`0a%dpOmϰvol׬ct]!bLW[[W'$Pd*siqc8|){в\j?slkIڽ6X}}Ӓak{x?=̈́b8-H-ֆKqqJi> ip$T+|x ?b~E:1Ť?LuyؤOZxK#OGȳYYWUFeIh`0(H׀noRmժ"m_{kvJyE!Uf,mfM ݻH;##X, Mְg_]X2Kuyn;%]%բoԉ.\gpp ]fv^y~Yug8]6m_˪%^;p&*+ `rikw7|sgxfq.6'CY~>?ڷ|=b6/bsک?6IנwrCZ֓$B`:nY_EYA,12rBld;ųo~nwͺ1͗SsshvU)ONqaϽ1G;pܽc=lZǮM[-Ë~:F86ਏ ~DqԤ1 uw^{-@1$5:mh\ECN֔t WÓ_55nvvnsW*+go*cW7cC*6s"7=|}@eEѲ5]7[6v=ؗwYJnՁgK͓li0 b8S3LjҬ,d3*aH : شz#`(S?} ]&]f(r:}9zff\qƦ|tsw/N;#뾰/ #Kgذvk*[V_N6T݀ƚYU%lIlÊ|x ̝""Z[̴H@[%&ڰc53 8yێ`z*Fzk%E>wѺB?=pлD1޾q.P$1מ|暮s|I$6I(a$:B/f]i[ %i]+fx>et_5k%?Ϙ׋ )rNEGG,d3rPvn8 B(]lZȽ ^}4_ٹJJ?)ÇFUص9-KnJ f|dyˇp2ܴۅbI=Gt!|f_q1_*ܳDkuEA"RDw8˗<8~y(ɣw/''njJ%MlUU(卓VXe-$ /pʑZOȳ;rA;t f)ą.vf[>EƤ?8ٕjf^W?v-gd,xlWwV+V>wUsѣl_!OO;{͈65I&krKfML} Dc<}~"d38VՁttʱs)T No8XBcgSNZ_UJ\U9'/tz܃@"e15Nk $$&frVyM>,IZ_=۶;|x0Y`pc}kCw?)Q=w0x{_wrYcEc1(h_(ĕQx Ƨ4Vsօ7XQ$<'c z'>;ϹFn,9K/m|Z+ ?ܷ9>/:/iᜯ9sFRh7?毟ڊbTtz)/ʧK}קZ{=C'_(f}[yǞ<>oo^f|O'߸E$bъ(6| z (+*Akh@ KJϘ-܌sFތ74A4>K!,GMAK3c?Z"ߎɃ-s/v10~MVp;lTSU\8\{h;ԑ眿 N&}~Ef{6̥F&|w{ӬI_>(yN6[E8uì=h<іN.uEp٭Cf}AĤchSܶ~=knE(Ӂ P\XȮْWARϙ21Die٧9ʠ)h)#ۗO=ɓfqʽTǚyT_N-dYTp+E)",DQľn֊eWSr6q eDqI|&35'ȿ>xoV"D|VAN\aw]>ێac%-M, O"ȆHZgӄCg_<{{lu.Mu~] -KqoÆneb:@$fQR[>YTp)EX2\¶f͒9"fj(Y򺝃)hN{?pHޝM>",ڃ\,o4\dl:?jQ*)`[Y%K A YUV⨫[ܽKf1j t$pAi |j>fh@,e  KĦ񷶢ǖFxcd+߽uk O'O0 rEA!q*,@*󱖔ܰaa!bWMnuPLA[8CC<^_k'iO<`Ƿ3M-dr%׆ H"fqmmIpaܙi4ڝw5ߓ#LF;s+ȩ(A.R^bGC"N 3j ֆ#SF5ywSr~f8%mg"(RJPhAWWcZtNC 23[[91wBL")b$!fcJ~>ee, h 1b_>˿:vxUR.p=?kMl9<Eڵ N3+{{?:+J>)}V)dŋ|wO3eI!_.F1AQp[001JX%Ȉݻ"6"/0?ص7/o];c7Q8e776lljBJgƉ/^$GKX6>㹧RSQ76ކpG_໏Ó9\d!O\_AJiDƉ$_`_ 2vkۚxj=)d 惎^?bME蔄la&¶zujD1DN_k+ɤPzKN{ow&%Zs_o_21ɆK)D٘hڰ9IsbWx!w-y7ލG5=ޖé9{>?fcrAFDKj3ZX _s3j #]r}!y(.}.,q2ӧ{Y]IJՃ6(XWWE3^h41C ?+h}}^{oiM|Bs?t$VFffc97fd_5A V;{5 n~%}$)e!1dAr!3mhh9- kj6?nfɻfpdAVB T I{4YV+ Rv8~KAõqc2]'paյ[M!3u%%`^^x$WuCh7iig*VY߾p!,z $`k0l6S(~x߹ 3f+މ ԭ)L{/۹o5vp)^WU^EI؃ D1}.]| iS2UV3@kg6N|E`ܸ1 |f6C@ qt5=qaV-w eeiLNTݫneUI_/Β!bJ^F4],3Po/+W6^A^~8݅k!fg"yS}}ץݴ[y9m3ի!#ח\QN}%~6i覐e,eeԗ1|`4:#2Z,],3{m-Lxy<˜u2qbq~ FG}#2j IfpڵFY,`tH)e+$gFtt4iM[&hSSO߹m7?-]]jogGc#֭3:a).Ʊ~zWINڈ%mi1IJc APRc1##h -R\ 8jhX^k79u DV bLAK$gM/{W)fΟ'&wXU%:<7S$I(9C&Y,8Pr0c1bvtML,z1AYH\Rɰr9yL1[&17!h)("ON&?-dXQa--5:$&tRRgPNN}ɰӉ1gzW)fI"O#%cǧ^RMj2lh0.)fI$M;%ck~?W@qΰ9$dܻHL1K2NBI6wA  k(SR@pgЂA^oN7)ǒa9R b".Ij8L,Gb2((8֮]qMF҉)f)B4')  !FYƹ~=bCyL1K!km%Ԋ\43l.%nw"4SR%-Eɯz$Btl, HR\Sֲ2+wbx<Q,t,WѯޕFbYУQ|ͩx0jD [q1zva,-wlLx(zpZ2\PL0 SҌ ;w-n.}2{WfoiI Xrj%" r~>R,ޕ)fnڴ(% XJ%Ú+3S $>954"cch (9oLL13K Ezb r$a)-͉2Ap[]bD ҨF)$ sKq+3S2 KR6hDW@Z9a_LhL1 B==Rztl6%%Y k.L10]]{zRzTpǓɰłkz"C1Y ٿc8jjc1")|ս5ق+ɰr^^H̙Ytp  n2ORs)]b躎XJļޥ7J,Yg~L1dtK щ^F xn""b,_Iv;΍ޕY)fi DIRR.f,@57|)zoZ^%H,]iB0rS̲-\Q7+ rb_)g2ŒXV'bEq=#:22h&Y 'zWP(eZ({Wmg-ۓaޕ)fYknFKDu"( zweNcYNxPDQD)+C4Bh΍rd~L1bΟO($^]k+j7 ib0,ˉz.\Hs5=M43NqzH20{WLL1cc/\@K[h)ZՊkFdPLҌ)f9BdpPGDzMXpmt:K]U3IoyY^`4L1!}};;YytM#ښх2ӻ^]mf`L11bljB\LyUWh]=n(8֯ndebY$׷Z<K:uKD Oƹabv$-3gmm"&"cQW~Ap_7V1{W|sfN"sm55IVB .w|b:y^E{m-ʤ_.Kʕݎhܰt0Sr]UJjSj *A3{W SVZNcIuWM,+y>Go0}jOQ%a6': &f6nT-̲y6kfi꡵X{Arl-%܃H!I][xQ!RXN'佧,3py8Ց^6e&>Yfkf ><uj }S)%V.Ls4x n",U6pZ GzipIVNB&zǂin0/Lspμ_T% tc1]ZM2#/Dޡ* *Vf{@0> rl[ޯ!*[(݁0s in|ns/R@WsϚ Zvwxy]P{qNЯE[IevE~G{{ +zEYjFz4O 3ͼǍ٠)>DQ`h2.GzNII}!6JM^+un3w&;A^rfEJ6>¹jIORɕ@EӪn!wX+w8Mc:Q\ 3JEWj8Ҭ&v.s?G#1SǞ[QV3 ފpnVc=hr˭ZOg X8b Qncx$N3H ZE[F`mkw< Dyf"IXN/n_Tl NÎkSs9JUb9ͥ(St4;Z:+BisOp>?k]nlR[2,Wh$NƱ} O-W jX FSqӅVJzjtz3}!F1KTőҨUlkvRgxo9Ewu93Ί*c%3#98a)d|n}Z T(_e5:M>{nɮNxh$V97f6ʎLy%C&W[|tqYcqSk~R p}$W:{dWJg+Pń~M=t,"%Ous"aLh3!*z:}mɨUdMm={mZy0st4JCЯqXg6Cɽn\›(\quVm*S_sqfؿʡi{1˔תTuG]V)7x9KzDS n1zT]טz:DI>Xn rnd-%3\psbNZ;r#STo8m'8~7K.e}QǾm^jxw0¯.> ZB+ B0LiÓ ~xĨW|xz޺ח?A¿^k,%3, -D};l,Ñ4:PI|Ydy`m^ݟNv3M21ߐORhpg2ߞp[lE39پ)"5vu"ij^hw08ś_>OuYX룛?7`+t6tMRS-uF܍M /^gS{=8-oWfݍ#VTGa6JN :fj]&Ʀݭҕ'C,&=R:[Z57Jˑ3U*4ةp{<ߞn'-g~HCVsb\6)~ ^ܖ痩s~H7ZIo,;aY^Ϻ,%3n8bt/դف{~7h]6GCa5pxz'p_0R:f,woO 7V/6z.Ռip8J/ +sPs F)mR痗K.N_N~/>΃ ci%o>#lPJ]Vr{rtqP)cZQviF&„v;1MQ0Εtv=~Kv>wb8:fOkHU:|mM^E<+sf2he>̹9,:ɱt@;lrZgiA/ueɘ~:Lc(: R{ksԸl:NYwAf>**`m٠.'W.p?.czTvUBd2 SQƧطw|zϞ֙zYaIBL5ckWPka[Kυ~Inѐj SUbPׂR' XNe="K>s٠[ss ^l 3* cqޏbۇ0lGrON3:9,F=m5x^Q ZCBxz~zͧo7kߘF̧&/Pby*_{asViTtl`}Std><ܙ 33h<羚g3kyZI^1>@W?(L&_| m'Lp,n}qK G9eGxS4RAwv\bK#7_O +ܞ_Ljw15a;gC\⢾tY1j祗k˦˦㻯}nr6NW[zىϑ?Op^Vn^]k>3oZ+}@c7:y')3{EInЩ;^ױeY+rfWW|jC.[*Q浽5iKr/\<cWudFb,֢+qz~tϭoaUlx^i-Gpa{ ĸ<0MV}l1X8XCSm~=+Vv'\ pKIoЧYF&L/r}ͤ̄V83+-%"Cdf FXx@7~͉gq"%B?]0.Qk+W>[t[H}AZv49HIoũ?>6gkTfgsa. L#NV(eLsppW6e^sKV [m%W:{{2pc~.geBXjć)EVfg{\ꛢI&]yTY~%xB*tTjN԰oK!.sx][P"hєE+|%=dܨ{[NJH~Z %M{ջ1gckCJz@&(H24F͗ #6Vv;6. Ep}f'>T> J*0ezi9j5<ؒL_hsu)*?^:R:[n\~j= aM5ޒRG#75ס''lkho[럒SЯ.|u-~yS)ttj` A5hcb+J׺L?\.=mM#6ݢC^V8bj>d]V-M ZXvJcѻňy&e+A% z*I]XIşs;}y+wb\"wюz'd0y^QiF&<'9Iw(2^nvs?NWoSx9;j UL9w{˧[\+3Xӛ,ZJzNE&>=ӡEniz얒x2(JT{\WoPka[ 7wә,:*DikԏvH|{aZa/~LyYʳ̥#\E%鬂^){wj/ZN [Lqlfy+jjyIr/<|IWd*I,Hޡ )Ϯ ܏r>v^V|9\~j=f6ؒ]˩ *RFE(ݗ9HvԱbz>NpnVzw8dNj#QsV@C 'S1Lo{JޡfCF,:5ZM:i &LVp|됷ړ=C/ R.D Qe$BT UFB/D Qe$BT UFB/D85N%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00llb"y*;95tf&3{sX3w{Pl67pwHb|,\ 6]#YUҰZJYX&x(ϛu<| 1}X_Hvc3Vhc3 >gj\661t#;r[w\,vN fsp6s}.[lҰf}. ۢEa>3/lp>|ͷ2N7 ΞC&^̱^}9c=9_~.Fc'VYb+oi?(Ml96pXϵT_ya;˦M tC`7>|<2t6?>C ks5}N;焱'%sHaS-QQe}N[rM9E>'u &91>'__Bp9x_PpX>'s|lϱL ,pcb{ZN~a 8Xe 1wlϡZcw˗G* ,vbg믠96HaD9Ӎ~lHǞGa,>7Try9q,>7^s#XSs U۝`g,>׊u$]ϴ)ezWCo;HIO[XF}1iMk,>˭;su,>WŲs5lOk` Vرcǎ;vQ >%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00bBDDDDDDDУ' Ks z{5!HKTوC{lڴ""""""" )bR!Y\40%*7FBRؗU+sY[5.DDDDDDDI'''K:"˗cJla^>];[l ] xcNp 4YcVa-+Žo Ɓb_&[KHJcUCG5Jئּ||{zclܼM%"""""""j]@c7CJ-kke f |֬ۀMa7x!"""rn"1)R."_Z0 ܺ .NbHDDDDe0p%vc/?_VX3oϙ++ n ~N"""] IoG/m%ŸgFˡP(`cӆjCJk,l4}$L>CR[ADDDՠ%_6l2x \\ݑ!tS}#b`͝^[bBDDD{Ckm@HM,'Ǝkg1'>r e%""ڡ}V~T"33 'bظx,d%bؗuh<ݚ0%h6?&""j 46GCjmj: g'L;!.g >[xTV׾W{:loĄ. ^c6L )AbBJDDDuBg,];JBд8p?z͹~• G={xaؐ'߫sj:v젷wOV |{z_<;f$I$xT0Fuϒ_yqZyvs~+s}֏F,p>ܼR玟<R/|a_E ޭC'`DDDUݚzjI%t-s]}DDDTDa{mjӧNttyHewd8Q12xH_{B(}o|ŧ妳P@BSl\^$T(ZkQSnRf2,^9v ?٧+|~&!\]CDDD0pIcc1'#"""m^O1%$%keA&c+W"!xJ&} O7شAff"GHebؼa:% \P~VD\Q17^6oU-tS^8Nkm΍\OnظxL|U`c?oQB !.A'z ? `ov¦Mk}azѓ˅m¸1\ nՔ)AV/6V.PQТEssڵ];[Ž7X_5&C®0sf`¸1L$$%CvGVRKkOg'L:Ik:uO[7`@8;a3};u\u<ۯ?!hdu}$صE{{}'B[]F5!>u ; ;.a{̨aFQ4'4n(6H4m2B7a՚=1PȪ 'LBRV*]177Û^#l!+S^C [K/5x FŔ[:4d@3fF.5 iiƴ !F?/? *И65/wl ])AInMH^qj׮yۯF č:=纹uAx5Ϋ!ސ+ Z.}tTvf: @vG 8; I-@DDDW)C/s/,XITZIƜ`$$%]QVR`iF9}%jۛ4j" ֖ʦ\|RXQ4xW7XZX B dd[s¸13rǜjVǪ4m2F Ĥp ƔMs4m2|}aӦ5d\߄C4 zq8}KHĐ1usȽSg"|gpNک 0tSDZQTsuﶠW&=!"""q1p{Rfۤ6fn &-vYDDDM |Fcظx!*צ߄|ikg͡kUT@„Jͷl{]m_mk ڦT)P}'"""nHx?3P(w6nܸYn )Pη7>xQlmBEOռ% ڈ ˗k-ؠQ Ղ VkgsβC1g֫8},,ė^m0öiq ӈ@P ۂMF/K#"""0pf {5!XxƎuun Äqc0}$!"""j4`\:5q j[B鱓6Ⱥ_Ksf*v9DDDDJf:$P2yL:&Ma_QւKi7gj7#3j _.nFТEs@ޭbSH /vDDDDDDDDM7#iqإͭ%5 ܌՞J%U 7ڵk ˻%v)DDDDDDDTMq.A ܨ^rp%إQ5O27Vpqq.!-=`nRR7ƌظx?P"""""""j86oVR:Qßs?,_.v9DDDDDDDdJ%Vb6&QռL bDDDDDDDDxT>BHMC.I."Rk+Xo Ɛ1d@Zh.vyDDDDDDDբCl\< %%vYaF;wD0$"""""""*CJi1b`صQ1pys3L: ӧN 9QCw5:6lڊe'v)DDDdM=dмeQ }WHN7DDDp""""E +bBDDDdT ܈S/bCDDDdT ܈}Za;q!"""2*nDDDDT4C=x"K""""2nDDDDT FDDD1p#""":+\R"""jLQqX)5& ܈NaDDDX0p#""":SQvI#"""2 nDDDDTgNڃ8nDDDDTg U.Qv}hse7""""i#"""jQ04L3'Q}j]UB4+%""պhVJDDD 7""""uU 82nDDDDTqX)5d ܈Vr+%""Qֽ{7g{>f޽N:\򉈈ժ)g!J&l\'vDDDDF!DDDDDDDDDFȈ7"""""""""#bFDDDDDDDDdD ܈1p#""""Qd].v DDDD*bBDDDdT ܈%$& ۙYbCDDDdT ܈νhq!"""2*nDDDDTBb¸1.hQv1?+S^L ͹܈`FDDDD&;Eŷ7`Јy.voG!Š !#û}bLDDDTc.1)yEM,_Gg/2.3V,-7pGȧK` iյ3:9u\&Ʀ I$bAD(0p36&nMCkm@HoOoXZX]سػ? =L첈(.._G@VRU޾hk{jm{!X'n d&k¸1~|z]PĻ}ظxM'C eJ%6mQ%·J첈IKѲEK|n]kصcs#GZz(k6mZ}K̽{qOoOo|2#"&nFƐixT^ !.A/K"# PO$v9Dg`jlH[I%t-kg pqv& ӧNg` }e>#"&.@T  ߭ aHg0l#Yb%رu8%-[b&DD͈J*ow/wK!#ܳVRLإQLƫ^/w;2=vRrn$FFu}dwdx.(|g$<%DT-7n zإ];[6] QM$|iu"jegC{"jtF  ;2~%SzFňv>^J}ѼAC)u(222{6A쒪LiuxZ*g77vbD$uRp6>;2KVZ%m%V~|L","""zqфڳq6n [3|y]hJ/NƝߜ cGVg`x7y|+Sq0*VǐAhG@\yˡ.꩞> Irv2O¼ p?1n董` XcեJ%yoc@ ;P}b/"οϋ?A1g3 yDv<1 F93. L Kk)X K+K:T*ܗ!y Rk~J%~Sݹ:usBV0Ws&:e3&kR]cnW8GER9] oRLtܻ܃G[e]KLJhcRmU&u_q s Y:3>ˤ躧}37R/b*0n4zPnFTR"8t(yYr굧G ,]^=di0t]bBMHBR2үdbs5AV\Ȑs#Wr} 21WHD"/O?Y)vID⿰FVRݑc s ej8\=urOx=أ;b}إPz) #v)$]=Ngpnj 5,X@ޝQ:/++ P҈H$ ܌Ā.nP79'!Wḙ[`ݭ÷PTpP,9`3ydrtØ~}0طbKDHTbv,Kk)y}<S3q'bD)˽ VB(QT [PP6m8"QCV4B=||gw$vF.I(W@۵mNF=u+K,Z5`npaѪ\t}Ү`/;ꗝXl"rX8 +ȗa W[a\,?x$:v] QCQx[92dgs-Z6 -!H.jjB3͛Ѯ,,j}+/ ^{MxF̩?moS~N<!`&n7W2 7 $z|x`Z+ش9Y7 QC7Z ŠP6 FGWGtksAT\miVܽ O|"2"R;8Un"R N Q/& t{P]ݼ0r$o#(3rq8>U~O$F\H{ Yu!MrL&L̰Err2* یqkG?uCQWo]B ۤV_ӟOwصi6鎷?V.ÄA۪_v"/(#V϶,w/kml+ 3ZK?OKODrҰ 0>|}9)v yb0mgmp6"ZR)v٢d $ܼW'oXoX-vDTC&˻~|^0<]UwwgWj{ǷuJKOSpM&ePkku٦.vnQGg׎kF:uv@~(*I8u,R2`nn2l3ȹvSxn{04Y} dOY%LLxR/#Zh8a G'<;M+HwTkK~q1oFt`Kײ+=ځqvJdE\BK{;طi"ɺsݨFBff{ "XXXMvZ& ǫh3ǣڴkisuO:r/;n¹/ #&ia۹VJi+kk67w^BB9 Uܿwנ ]Mǝ[7t4-Ν`ݪ Q'_ GNz{M;)Gnǥ+8dg'Z@^b_B_P$v ؇8}}-Cx7,,BW Wo++ 8ŘaF6Eȼ»pjo n e>|q/gdC'Kr/sZKD'ܸuIiȾy ݜ;!PEᎊ$\NG3SS$\N6aVI|'\ʘ1O$bODdfg#ݻvE7gxS0[8pW{Ԁgq}Fn.=dEgRzܑcGЮm;&ۧ/⥋hՀ>t/+*R.&ҥH' ;=ѭ,-˵).VLfw/_Xn^hg#Lh=[R׫?ǡ)*+WvmanRxv^V6#x $)l{nY7ano~4Mrag?!5)E{[Fkk\8*ԭoHkCs&tV..nK? 2yakL>Xjsi&uϽtci9_7W|9u*8/pl^$~@TZZ*P'b`k5 ';zMz0ؤ3@5LVsQacѨ?P,"r=4CMz1--^r VV혉/#rOBhw4j|*9{J65DUa%Ӳ.b垿 @5O^kWG^Ć;Q=2+3''^6Æ)vͷ' >Z?곷#gq"!2?oV'r_̬Ĝ̟"^KϿߦ-}V6VxQʇNƶ}k>p*2y!V%v^>futO[EԢOA3)όƋ#G1#w9y__)؃’wJ ʽvp6VF-(,Ěi+BVn ܔJ%[6i=8y,0gv0:vڧN5w?{w 6q,\9LM&!ؘC7T0tJb{R+lS3lpdidDzU o6]JdԚ˭tdB^٨?!p3pK-Q0%\Nz p١~=QpVirp9ܨYbJ{"°'" R7OUKɯUkeJYԔ 1N5DGjӤT*bc{Yz^!p[8Pٰ Ṕ7q \IVQEo/ ]N0᧎džÅǃGù*HSGUي {`!L|fٹZ?WkaMQTtYS~7;:bolg0l0^5/g^qs`ݟ^ӯ"ꃻ1f*q ͘_<+Y ^8([Շ>nO@ji֭0i |Ay4Y]=͸ /x H$LI0j꘧i+$\JŶ=B&/Ėw.xyϫQQ~[i`07W} HHIF\>Z} Xʂ=9.:+8p8 r9f7gB?XZX`ΌY;O0vޅv,pkׯ(ȗcOZ&tS;w7U޾;& )ı#QԨg~+*,|nɑ{"ͭ[WZ޸^:Q޽ snɵj3\uҪ)l(ǹWrY榦usElJa11mB 0zQq ܨɱkq4j֐˂|G"z$AßE箞>9*3qʌ _H$wpȅ01%~ŲUв( !s e>M^>BЗxMsN%"YNPTK?$ <3qOӿ;6ۅ";)J4DYuvu Lcv{Q_QxzT֚ [̝;z?"l8~X[+0I, وʅHx 6^Oу H`<co~ĕ榏]VhצNOA>QM?|:U{ CE]U K6JᛰU̓..c`/_X 2y!~:i㞭tkEZag/[gW!1'Ob_/c?ci{Z尶—˖^|w.r~:vp@_\}ma޻hm~%,--}MX|`'_ gQ?Dg==zMV ASFʢ4PH$֥.oܼ;8r"07^|rQmV=u,-W:q. }P\sSSQG~-9|qJRbus¼ܱ;ٷ1$]NÕG+(m-,x3.OW[~޹sAjz: )ɸy+OzYUW_~EXYZjH$d~4ttP1et>ZTkW<5t:ײ2\< M[:8R/Gq6QDM7=[6!+#SǎYL >C=ܺ\ݜѩ;9SWvu37[UŧGa^SҾt.k7vB'{kVvXЋW /,]#ľD CG#ph(JBvVU'" 6FZ=jv^. Ua?ԔJޞ^+bag`1hnmږ=/ {.NvrRݼY: X.K{6yOٶoޒUUo~޺p^>u>ځkuPկ7"Tg0̂TWJ\*)=CvlgKg}]JQ˺qFLI+9_^sP5D˗m=>=t zmkׯ  _TZܾ@YGEr+, 7bfdp'%~nz\'s$. Jܚak$Lᇎ"6%Ja8p=ڥeWXؗLToH$wpB{'xcɼW!;m&vl^ wp\Tfx)/7ZwZ2.{HUS7ެp {{$}]PP{ \U |Dݢs9Wm+k c1ڡPw=[~u/PTT\N-D87T|jutwaK{8wC9^.p;^Si]7_+W6zBzjt߯TWӼq 5~ffe V°Nmƚ'9YߑU0 ?T剮BFD5M _}BxܤFVѺMH$P(8{؋L;Un5,M۵oS+tQʼn a qӴB+CT4Z][f|%SgM=TЋ]\pt</>94 gjfɯw_,Ms3C fl YZK1չ:HK:wZgfc[ڳFCiKk)>vm aj8̭Q_+ ]RK×7r{RcE$%|!0Ana;2z0H|^Ozi' =\=u-i gU;uǕkV2̬y.ˮR˗1rDԖn]K1䩑w\KsG%2nf@{$}"tus/w KK+XZZaxjHXezZ%4'& mVja*%&bރZ*r-G+ s{qBVuzR+ I<\ky OGd+v5:%+ûxx se:bB ikz]MwAB=9w.Q,(ȗ =͵ƨ'-V<1i«#K4{mmw\LH/b ~UpԹKiU(o8ﷺ?+K 7l]:p\i'{K3:}_5nOǛU穕%g@*3OU`D$>nFT:tqsc ^ϛtQʹkVX8!3ι a[^@ ȡ§azT6B&/L^. p0ԯ XM!Q̙pRyԺurD8Tכ~vm5vIgjR,bC6Kk)ٗcʻ3x!V!9}*[>q/=/ +),,0u滐H$puNkPIT:[kV-abeRng={TojЛ!yLsH;"+SNQA`W֛A`ۦƵgԾکEs𨣘=a O ;cT\:Mr烃U(]φK3MkaF( %U@^W&]rCJKUzS' ;{x5!" "dO~ڶm7uvZHA.W$kVo(gl-KY58R"0G)Dt?T*yAaP_7WLQ7}4C7J0t :^)qXq'&8'V2%j,:w-x _m+mv GK)W*8g^gj+sCG% Z5-51RI ܃OOznZ vl uU:2D[vmV5Uz]fg[&ݖUmPOoaLE/.U@ ߃*== ]?^]K{+'HWni_u45JDT= ܌)fNf6 DR2}^En#9>[NQ=Uu,}׶};Z+5T/>i2y!Yš?8ܺ#|OL_"t>_y]+jnjuUw"7itLx%Bw8c9ڴη? =׹sSS!` 1BvL FZ^D &N)<=՟}q=+CCv^.Ʀ+=?Xp}`7 +s6Z&ὸW |\LB58{\?+l,?rT*_6}+>x8a½p8sb(jxzP/~iie\oղE*m[K?W.>x|׃шO-в6O¥jktAzo:5ϱszyYYOXϙ|0کcB.ly- 禽M6ר^ѓ-.ݢElQ8H, s9,zf֭0Ig=Ԥ &mҹߔYwtt.4( Xj.L &Q575ƅbM҃OVuZY`ˢ:{{qY?tT8ڄAѭ#g1`/;7R+ ׻C{CP KTi! phzunfi-ŸI-|  U{ͅjYp]AHdge⣷Q+(|cxxBjydgebODD Ϸĩ3GoO/wQ' \)VY(ȗu!عmh<_k3FVHK+NE>,+ Ǡ{.i[~?v`imEQՓǣ6GA~~ r'(JDٯVC¶l#'tsu*XϐZYM籓.]gN5o!]M ٣[' _ 8C|a3d`ք:߻(JlݻgST[LY:w^(2k rO 5?h>ig8ѶM_=u t{: r9m żsе"P=guq6,1lF_n -,ZiAQPfѽFj=܌eO_Oǂ)+p9HK31 |Zl*\|{*w_UX-/o|ɄRĵ}!w^S^)_0o5ހBJy7eXʤ}`cSʚxa{uHNAcXM{nO8 ۫č[wpFjIZU_}5'1}qD<X_ u8?FK,Zs$ fN@#rCTƭ[Xa޽Юy aeaIϨff]k][T*q- ?l S}z>Z旟/lamѲOY5 =_xWrnͩVx5ԯڴ±WU榦UnYuvvho55vV^(V(PcOCH$6{>&L nCGg`~k@A^U353C:rehgPNzkTCD?v+ ʻ{*H0q L2C8?5U{G,2 x\qGwD2Yx\s^[tBGphBܽ\ܜk pu kC]swu»o/SjY^~R+ ,;^]Jz^KW~Yzbߥ]=^yz8;__FlGt/@bU3 7o= _<[W=uQύwN vsc-|^qf. ɓd>R뱓poΛ Xje)h D3?:{iJ@Db&K++`|*D5PKk)-uF!FVtT }fCMMgM7$j Ljsio_>?tx܊>n]x:Gn]Dۭ+ ޽gD"/NO7D<#aCxtqCxw1canng"1#I㟃affX7Y>^ffxo<|qqglOSDPE#(~;}ؑh]bо}kބYU(&ckہX<_o],v) ||7y#97r1_aQ=w {j-[0m|K!mZ'bpK!>*(Qg[R&LL`P$1Iv5h+>+AT ;v %y:֠N=Jk}T*qBU_k{UU^-۰YZZh/8ֶI5_a#~;OI>.yb(֖z߶*ȋ `)LMM okRZ[yYM*M3&,-`jjfsT徿&R[X͘8iZ{"w"5\zYZK V9Yش-=Q=gaj)=5ajxFX> +D"u-!l]).I$k@nysSGUQVݺ۶3 [ 㞛TDDDDDDՑ_XBS*Y ͈DDDDD԰/.-|k+缪Z,ZT*q-) ȫ}\axi*_x"k=7}0tHnFzݾ} oϜV0-w$}mb ldDDDDDTuM`?oze5: ܌D϶DDDDDDu6UkR""2>nFTvM M[6m{"""""""""K++~k~]õ+H """""""j@hB ;s?PK """"""""=Ƥİ'wm r:)jWv;/_NwX!%"K &JJ*v DDDDBq%)O7u 5t[rMZ=g4/tP?PQmk%BjJe  """zCJL_vloj<ϱ(V9u`];]N{L"H'}TƱ `u;#q=+.DT*q1)Mң];hmk-v9D+86nudެ۵=L+H3uL"qP4  ;cVX"TG=VR s/4D}.!j"zt=JI< áC{ͫy ܈Nʻ.bQG 4JXhjƌ{>d .^S*E?F \'5)ܯR)-G6ir0] 5!͛aȠdˡ:VX G؆o^\R n\JIPWfD%p͜;[?vao {t`Z*X8;aX<E.^**‘ߜ vurݚ1'/ze%*ǭ8x:ƍ[K&fw!˗eXZtk"Rղ`H[IO.*1ah܍cѪQ#VX ǯ÷7F&[353m;{wO?(vI!Ma} 9)*s'/`d 5!u޳!.A%K{q;9:tRӰ?v-A&cIbEMP3KǔX`6FG’CRY8{{"9^CT]:q"%ׅ|8_RDcRRҐ}+(, UPnQXA0Z$|ngȅ|x]hΞH{Y6]usE QScw1 2y!#"z8x(Fx. Z2ƍY$-=Sf] heJcs&3vϙhy,=i~l]U4NuTp}hDߵ?v{UֶIK7֤7m)SG%mMueMp4ۚTqˤu7 .ߠD5HUGAs&wTC5 P ;},BE5?heme޽|У'7?+Q&$%ƍ̫ nnVx˩);/ՃB5L"A//zýZ=/^?܈zѵzПJjcF}D B/غ} lƁbDDoOo,p>? &734 S*Om\/vD_ظx$\pH"_#"ѶMknDUм.zKHLݞ԰?xÆ<)vTyzƦ ?@'M$|Sc&ctD;Q#pjbQݑ壨EEPQU6O[.1}I8.]=GP҈n"153oG+aO Z"hN0,Z;:?-Kw.@ j;vF]"cDaDD5o8ZKfbT5jѩs~}7r7 Ꙋ8;].C"t@bJD Nk7^8V25nd.emآMc5 'U87")==}8 'U+z)!FTաUR(8u,EsH)5h 'UaDT^c()_7+%"ʆqX)Qh|q ),c!mU!IZ)WH20'"R 'U ߵ[R5nu@_|gLUnP:TQYU*z)%"jp._1h?+%"7#*)UY Œ`fxrč(C >"vDT:T"#3K첉(߳VJD7;8Z #< ߮RqQCPjY6욈 'Ua&"j0qsR""YU:;8aW{<+AAJ܈'Ub/7"z:+?qZ첉Jk&vM3"6 z_$2٘'hI)|΍\Lxq:C.걿6W~Q'UKHL;fDՙVc &NWfP-8},n%U'`jx&&&xu~""҅=܌ѪM[lf eqmndc3ϗO܈䅉cı?}~E bID`[=ꎅ#`OD֮2ma.RJDDDDDDDT1p3`^3{נ7bRb%Q 1pEVjuN݄;uv'PĚu? |n ƢW^'TcMM?.xw` [!: FM".>[Stp ̭[w7KFܲ%{q+6p jzjFBu5Fݯs:|;w#hpLzؗNL3_y.X?fx#!)0jd <6&fI|B7a`> W7gF7Dlދs9Zo #+)EDR :w>ιuۯp`ǰjM3[͇{%v9N"2TWZc'1l#jf/߬ARH;rt*v[zIRեET5onߞވܳNΗs#iW21 b_:5rR stC٦#˗#J&y^RHDD\\ K>YJeT&’)QS91;z46(*kpBԫb_^Wu}Dn-ڼG2g'|&o s ϡ_HDDDDBQ]ܲOx ޝ nzuFx8% ) jn⣷^^5>q]QY6]G.[˪@Ū:-`jVz{E? e>]'vYD JQ=dgޡIEw¶v lY>}<nmŕΡ-:z.M}どzxZVTp[C0pk"X%珡& .N cG5Bh0xĸzP+V(w'F|}| Ā+J|]:2EJǠXQ뼞q20v^>%;{"Cnt5=[bfDUQz%5G' Q, Xkj]??zz}J7BT8x:nrhcUw"K^V--8%s'o QX|ODy/,OZj2ZV1=.ޘL Ϟ:*m6BP #Oc_D4I~Ԥ:ʥZ=~kkL=:; b^+ ܊PTxgԔ_c&o[W#zQ3.BYaVD'vk q):bݪ cSR[˅jJ: ܚ6T;[J;8bm;!;+Cx-i!xXZwpler6>ѫkmlQPt\=aIؼKL=_ΕλKܛHu"F%4*޽~Ki*-=* 6zU4󭗖A65 zO5=>[M^ ?[)vUҪMۚ :7aZ3߅w/\\1r$1oo.v <&+kՔ6W^FJj@*ԯ9m{KUe{zzFgIX`=8ڷ+ 66^6QnFdhu_3MpD4~>#O@Kص[u=]ЩsvQh.Bռi76R+afέ;HL W2ѭ#ڵV:oCy29ӯ[lmZ =99]^+:x#hpD;NhrouĜK W?gf8½ʽ kkصi%\P~}S2T?phk˖-0wסy\Wxݿ/v 5fai Sf=ݲ2QX [J%BfEK 4sg7XjcPC+k>'/lO*xxB1HM>N(˴G+Tt/,ZҠO/+{J%RHG6m Nge jέH:w=`668ObKru/'|h+s+= Ǩ =\=|3s . ̭[hpJظzo@ s˖P*Env}Ey/;Ҋk>߃u 4>]p yXvlڃ>}CTjC7\ZqJ*kt|>*-;]Q:W)/+,|ͥ <s^k9:_usŒ):#Ya Y+ ?= ӟIXU9ui^!~x0}6']BW^»kؔr5noޚz0:kto d4-[=0 K+;8 З TUXo.Ҁ Nͪ^2x}}+yK=*]ۄe}nkʿsKkVªjEQu8T*6#\L:|Oư1W{n5JO2Ckk3PpӲ׬}l?)MjPWfk f k?/s &>1uzsϵ>[!F.q~Icqvs(ʿ2uWt7EueKh20bֆs'/iWQm^cw+fY_ UIÄy];b/ CEsnޔ?jP!FV!_xUO Sx85rDEc9[CGM-z6H\:a7yCje@5ڔWBVXT~}Uyʴk%:ס_վW6_7Ws]׿FksVAå ծꖴ5nR)v)F]VhX0[xxc5~2MMgMu93)a_+Ws裗ϝ6KkX%(V(ʵK?S| j1)}YMkWjm}Y3RX8w s=uT+l3΄u {"p4Jϥ_?{\%jrϩ/׬~NUPhm.sYX(uwT*mBfac1p:WVئM? -ߋ}s s6]ܘC|zX("x"G^]-l?9[`}t.bӧtyQUIM{[US..ɉC1ľJ"EᇎBjeA/ C"~;r~QؼHҍ=ʮzۃCG!_#-fE!k]J{iz^O8cqOBOMP3aP|vְQC!~ޘhajlf=dB<mﻅ-hpCp(.϶m[dee#9"< J#N.]^ (DkhȱzzIMg bOT8X&>u۱y=´ɥ $ &GK$jrS*P: g9}Τ7-t5bOĠ _Q{^/V(KR,\VW@ Xp=gv{+Bci-'$?x$2. agS[~,X3RS{"`ėkQ ۴vpum ]-l9_~Ξ:ZfOB]?z{: eX`6>[M&kejՀhaJl "zM>IK ʏFL{HMIzU\mKS*}xT># ,.:)y5u ɺsa"MV*u|ʵ?S" rr#j侙;Cz ofI$xv@z! Ӆʆmj P]Ak=F6~El"ZYU9lS0?5?K{{ -̝=uT6qLX;I{"F["zZ>G>IԹYo..BݦffZ45 ͞/\Ӟ0Q'΋;չB K+B}A 95Iq^H$k**4P{'?Y fcKiJDmPoEc*ȗZSfTy3^~N[آW #뚡٨u׼_q'ۿlV.kǚ6r$ppIDATnM2s/hpkmc ;բ3Gjv9]:]j=-vj}Sm-0ә7eV/;:gƥ*Cg6ha^h=܌Ѐ 7?; ^!H`aꞟ;rѪMibqtxG4HNrnBxa7'>S]~H5I%0tut9bSRR+ {xj-0P]Q]u>߭0]ƄRӄuZc ½=w|\쒪DTFvD5ϔf(IJW\?@ V,/TڃG=,zT:{Ǚ Ǐ555$B+R}:wV`ezyjyK*wM#NBNqhoZ=bOh?x$IGV:$wʦEe =U{oGCw5>., svs9ObٟG;6+tyHH!a˺;0/R/R>>Po)M/Bvmaסmƶ:;eڭk!Wu=2}RΟƤanis+)2] <ܺ!i pqXQ4Oʚmu._=ʠ\yKtb\ʺxI&/D}ݽR+ |3wf7_7W!;f[١jΝcf۵jvTY[[!hdn qh޼~DTYzZe_+h^36|<ף _YZNa\y^14"+K絧$پy܌ǣyOĒH$°ي;8WTTf޹u jw/xxBBK$"%P؂|DaODXᳵ4{Zkhڪ/X453+JV$sQ~.Nؼadrr;(~wWꃁ{ʅ-r^_u!gg[ Gdl ܌̐L0sa]"L݄isKP$!rzDn^agQ¤QQ6!0ua8gި榦œlo??"d\ũ2y!~[׹>W]Yn 6z_kJj^>U3+tSB7!hdtGvmaӦuVmUϼ3P ah0Z~4UԳN_ohJ^!*MRzWC5S33!|8en"U$˰blMׂ5Q*) ~߾ߣ~OsNPp[1pU (v9jIe=>8{" 'bܔH^uh+OvVlf a7jZS&Msz ,m W/t=O0d :w*Z zwE?PxsLk.(kI1t0o j7.4YZ[]nFk^T YjS,,?Rkc 'Pus ,"iNА*Zآ-<{GX _G8t4zoM(Jl^ֽKxlkWD Qz$L& '2_Wv}PQ4Ilf86 Nľ%0p3.RD>G m^1OOI8wPR"Kje!yU~Ow zE;/Jf(Gv¶CEp%|wTٵcPD^ޭo‹Uy Js.wwM.7OXM}v);t=-+DL+DDBUvN3ǣk%pKkxlٓB~X|m[)gcW5͐ῺjS:g++sqts(ʿ߷R؍:jTgQahH P׊a%3qz xa|te("jzv)Ǭ꣆_\\UHa[׼ruAs(mE:G3T+KssQL"];}- Xa̪@}\Z5ZHz8JJ}2tx\oWPAduWHBYZVdp_ }xBAUJ̚3lh~5[ҕ ZZ:lʧD D ٯ  UO.@,XvT:2I/=\6ׅk]ھ]1BX9||`_Mh.ԐzGƄvo /߯p#}Qg1Un8' y}L]5$a{ط`Kt'SR[G]*׳2bH$ʔQPIiתfXQC* (^.lWrݿV՟}w^ fcvtN6F>;g ͅxhᄎJѼ lZ֮DTVi.@Ԑxjݻ[ڻt-x叱oW {~}>>Z)cxW?c=pZǪ6pp {=pWw<> "->uV[w6ގk#ymDQIa_:ЕT҆U̴ ۡK8<=#lcJ }59ebj]s/zc:dz3੧uT* |t͕)W8չ_һߟaYs6^O=}Xٓ5mtF+Իk`AßD!-߽ ~\W0N@P~Y52Ꞙzu]meHyWggcD),mjf&嗝3:S*X🗰pxt wzJ[Krd\a2ks" O"CƔ%ugO$JԖS0'&"6eeN&e׹苹nneY㺼|Z5|(ΞHI5<*5tM}OJe|bLD[Ifh%N}4iצ0ZlJ*]oNxzzDJ%N'_Э1uusElJ* 4z8|vFgJ9 1 ?-'Zy:; =K^LŚI$0?L^wK@ja[wwv-Gk^<9{Gdge"z$Z[`ؘJkC>*sm*}\;8AT"%V@UbR-`̘&\Ѥk1nM𳼶eNin-朧8:7IQ;{> : 8^8b{xyj^&wrYo?a*ΊzEvO;NLOf_W !d+v/2&QCHJA䈍gw\r>{ehҬ-Y>_(p  UsMx.(զ} ?B]$@.v7&]%^R*+ D!Uȧ rWxnL qBˆm hYX:d2xN= 5[/zqpUwO&Ĝ]xe,=/#Ep0! A)U<||YAރ5}/~] k2sߏFFTU7nhѯFWu7~baҹQ/Xg"\HWn8vnb U ~+nV\M[ 1H#"_1_nںkW"vUJ G?-uDvn._8Krvc{K]QoXzj_/j*%u"^C7GDDDT0p&Q7K{)r$2Bi^|O8Z߰^j3*U7+$hh4HM<; āۑ[-8;Uķ9Y2$UW$k&U?ID4 V}8 h38k3Fq.7"""""/u TO)G0ˠ*j uuC vT/l 녈ac UR}M /1{q""""""}zç.ꁢ;GRBUM9q1ڠm{1ՙivx5 H}t h.\RȊnT$DTR@ЯwɟT~;|бCԥP1p>tCM{M8GGPmi6hٲ9 jùfЬYSK* (.$V*xK] հ!wsoF@rGѷOO88K]U7 \vE9"S0nb GH]Ya}X4k*>\ dATh4B^8KrHBݻv||:_7.j4).1{ۤafmf$h~aH8} gChhbxhFѠ]׈e "E/Ѝ*FX5/b8F!wu0yZ4V ݈ Ua֭\x̘> .$ֿo3WdddC1E.^"6{w];b@>!3A ܬHAE)P`©4{;qꗝSxڈ}P fLWA# {S7ˣZF*BR5|w&@un(Q{/a1 ФY #"+*QqZvV}ð e2tݻv"Q $Т7 #p@O歽ةtڡH 5vW.5|("v&,ݺK$n.0Ç fVGu`ۆضa%Q55b [2X'""1pHQ 7&Ю> d6@}CC&c7"+jeKA,Zk(*Sq q?'?Ah7f\˼6nx˓NQ0p"KVm 7?B߉ ܌{&*OtG~3#4mo$OXgԥD,QL%g$Q͚,I7}u1ɵ 9Q;{[P U|EEzF|4+Q(HM_cRCDDDDVʪt41a^SH] IŝdFDDDTG4"?{>32.jo.r%.=ܪrw\|r w 4v4>R7W(Q+_aDd~0<~ ܬUY=]0zs_Mn $Ц]0 nf+115TJIRHDDDDU͊ !?d@FT NaDdCGF#uDDDDTI ${~۳Mo֍t<(]UsfU4TJ5aOU lWC k顖x(v@ gYxg'I '~.D4Vrƙ:r .*=ܬI?g~E"ݓ\"q 'R"""ڋ=$*}<3;VpRK]2(s$&%Q-͊7}3Qmp <|h~̽ǽ ܈$KeR"""ډCJ `%?ҮfpX)t8R"""ډ=aJj(r˩yYυc" DTl߹cZ)Q!Jǩ#_Dz-`4rr\z%=#M)*ƣvGdz7h h7"?DD[{;;ԥYh4ضj2Rj S#"ܹT:D >^d&tjcݟkB[nd%jȹx,EMUg KU\5Sj;Ef_ꞃ"vf aVa5t ܍H]M).Vc|Th`fBf-OW`ŸH]Iࡣ<-~8{&2l#*LaqL( ƿޫ??IHe9t-_a~K *0q A(.VK]vNڰəWIל;gWDT+1atQꒈl!j.Z"u9`fMfv9yB;7JopWU`;n>8o 5|򾈨8}<2@Rj.\,u)D6#vfvŰL~pvc.$b^8~Id j@:r^rcfednNnŅ |T!u(nh'kM$" Em8sNRlB"#X$<);޲DŋǞmD1,u)5Z?6tTf1Q V"~pp.$g=Ae }qq j60i u)JeAԥΞb<UJȒE 2kB H>wLu]&6t,88p!zLYPa!RQx ZAHb7ZoXJe8ny)p5(.T׿s/}n:粣DDܸ%_pyn@h"e#/;`MZAC;{aUϓafE )k I @SoADdq>mMꒈl:ȔKW٢c; 07EnD\ZK9|I3)ϻhߩ+ִ9|-Q|-"nn7ܶ?muyB9^Isk:RoQ"K]P&k<}Nܒj7+l@A2pDD X ~eLh!;=]@jҵud89]ZDDML>_bw׆PEY; U;GL7,V5U0F+qPUCP׊yX`c[HD{SZi#V.w? ""l?i6}F/li U>~}|0wkN17E)Fidp9t:N#j@L2>sc̏zRWR*7+*/o{`i&^h_&pg܁1GIIXiΜ<׳K_?9! gE[ADdīhYILR0l`gWm=?ܴKmr'G(TEHJ22T߲[v^p+7u@]o3}4Eh9IxίnE"h,>F|'"gW9`e(QxF"%wq9`tմ?%lюcCH}[cs#=8r'G݃1qxtp(.);R7j{ՀDd& 4ٛ.pv+g$?!px`""k*ob~KH](P U4nùTB1ԷF'%"]zƪ%PT`׶o0zkREDd҈={?&vv&-.)٤O_^O'݇v )s^HTwuj ;;h({ZLJhq3RRQx.Z7o`ҝrUy5͛ϳ<[4/z'R5FG(T*hkWrJ4su{S7G3G{\Ӯu 7+25J|i"6h, crH9L8{[nDd.1_}m~&޹k0<N^ND_=lR &腋X a$-( Bv{6խԥaP.y*]L(ǽ'O ۽: >~Y+z>,}(Z9_e?lUT*w1AoE\3aLH7PW,4N ?U*+ 99q;t?&==ToQ/½=Sq YwCF2S]^F3WjwPpH5=4zp_Kwuꅰcg4q#ڣ]^;"V12鹚#p s*zB}niе>;/_/l:?Ɔ9mHq Wj*QmPRU$Ą)3+Cc=b*?_!u ֈ=.w?@;GXrFDU` ]7,}BM^7̄?#)wqilJ1~A< m9>5=о:cԴ'-7TXWCVۢk0/v>o9jpa[h &|{YYٞkzwuS̍zQh%t׈:/z^%nc^݃ ?BXu:=ܪٝvwJǹIKaN""rnCb;%RM' U^vc˧70{Ija!559kȧضa5T~LTtrԥZM݄?;at]@s+%۬eoNA¿K;; Zbsz)l]#G$ݽ`4E@D (0qlhUY1pf[¶]kh`ea߇~QY/Č]>q9AM `g'L.6~jl.LECK׭\,uIDuZffoH]FHㆁ}FA5g.eokw슇RM{^=L;Cç ^8db^` _!3`V &=3Jw5wnݢz#[~.c1UCJ! ӹƿy pGYSG왤ـ^ݱ}.8a1RcLu75 cz|U#6rWDMuġfj鍈p.$'#! BTDd N} ?~ J:.7=8"};|oXޢ:%]b< snH.*.6O@tDqI .3zW{0} e͍/*tVtXm[”aafbVHTz¶"" >u_;t/HUz=[^ W"m&ޒS4lK8G l^ 󖬁=%3^>[^BvvB(t\^c=\rjEFRej.]şW3ž~xn_1 B$TKvzZXtN 1BعȆ~-(~o|}Ϣehִԥ:}Bz+Sc%{&6ZhJvXd F{M겈!y~o&6 o:V^E ôQO 0waa+KN2a߽ܛXg< c7оOG[t.[U3Gݽh`a};;Sm,:WC {/1jfe>Uv BB^C kG~æ ( Bv{,:{.~4ZӢ﩮8hU r'( T8R[CŊKJj> ]/Aq/70{feOiai!D=q9Rߖ+j'n5S8) صn-QcW:ILAذf%k4ͫIMD[e^l!Fg e2}#{J]>b̄)3|W.ƻ~!uIDuӥDܼy &%CYUP&È={?;| ݃ᤣ=|eb `%(TE̹7 쫉8K ahқ k(e冎od/@Uw~ ykrDuQu|O:99`Iضa523wx%i>(FH]JV7@;Y8|'԰v/W4|#/n xBX7;c],lG (-0x1iWM+c+q .>h a+ Hp F-r(ng0?9H:+%SӗPdg> r~Qp&K<}_~ bv&"<<6"#NjmW8|x3_aHW 'WլYJ#{d[5=0~bs@o8"[w"FVGVa] ۛ2sh׸z;`epC&W`9|lgl6뼾{324"ߘ_e[~y*:C7,Cl |2JyȆd2NuV޿ X'a8KKK=R<ԸJ+qc>m~$RƤg ,_X"bp?zЫ)C޽|cjC;VpN(崫tpUg]o9CTk+"E(ܫbOx;9iXv^Ϯ[ j5HUrw/D&RNDuLE~D`ggb^FaX.x8+:<1`w-"") [w #C;Zt8DJ/6gU4L|.!B8}B,0v~^^̍zѢfߴxH({+xuBא8Qon?~EcuJ^φ@>Sokw{'<'Zjq!WԻޜq CQ#q=%C!H/lG? z ٩{ {Nr88hOnmDdUYQnrעDFJh?Q[d22sS#8>m+ <ڭmGq{]_y~ E][QMpCh& 4Oo5Ms-{sv/T4xw.Eŕ:ν-|l*|(P AokwDtE`W䈵B >B B5do֢5f˴uz5ꂶgzvǑsr 62αϘh<)BR ~tД-Ws?\ jY]r9̏d9Xv=}#{a3.VȾQ/LĂkѤY-R۵պ8}Ϩ{lv,Ch&w1@crXΡn~z 봷{T/S.g5v[\$U|򆠚:{`/ }7s5}HT>3mXz|Ez"85rл=y{,4sc;aw-׵{"LFl[Cžvv.kz^8^c!Jy2V&s9d\X{RؿL=C1"""""""]k45miCc9#;H]k uT """"""""2LQFL'/'";/ykFPxK]c7+xDDDDDDDTM f[Ю0cFDDDDDDDT5ɰaL\; KnZ>ϮUî`fC91l߫14#"""""""$qDDDDDDDDu7+z&w ..aŽoDD)sWa7+zX:/u 4 "ŔR@DDT+)UwC2j7k{(C_DTw PI]Jr5+m\]\/Z%?YRBD~+OjI)򔺌$ۈxpK5KJz=ARBdѹsNԥ* e2K!" 1; ZCRj7"ZD߶^X//*'u)D6c~@jJԥ ss_"HdPz#KRj'=ꃃ.1p"){Q1PH]M[C>=`/u9D6OptDvnشԔD,nr*u9D$v>e9_зOOl!u95Ԙ|}MJ͈ |bwGc1{RDdSd?{&nr,C7ѐ56Ʈ`pOT98K(Pa^F~ITKa Y9mH)p17#"A06xD ͛·;?fwlR jXL?F겈lcW`13c"BBP05mWy˓Rq#>*Os[/b0yZ4&.o0 ,"z# .\FfeICդ`PHz=bw!wsAԄ?^v]'@܉߱|=uLlƨ; ۈH>(1â@RF$sɩP}Yo럡 ܈j1-0;?,($1d#=@^ڬYz{.سc .%$[8i"?JI Q1&"2O@ > "cfMSJDDDDDDDT1p鈈nVnDDDDDDDD@p"pc79"""""""Z1,#"""""""fpDDDDDDDD7+cFDDDDDDDT1p#nVR@DDDDDDDDT=vwFDDDWR@DDDD$`Z% YM """""""8Ȋ͊hU{ ܬQ!DDDDDDDDDVnVEH*j\xEEw.j^Rj q-K!+  =.RBDDDڊ8|=wQR0Ç fP9غGl߹KR ^} -[H] 2 ܬH7bDT]n؂u3OeQ-P!.\Fl]͈K <-ήr 9O2LJJj pi0A@K#""Z=6"~5,\Ǩ>6i4Tr'Gȝ{1.j2~~#mla7._ L2N $";{{#PG>O>Ӣ- l |DˆБ: cNX/crx9X#K2j=D!l= L}Eb\Tl۴WRp8N1@6ϧ|zc@҉nVSq6oX66A"˯_oK*2]kYήrm ޞ)̘C.$^]0 ޾REdԝ"^IBt:2r79͟ũj7kcFDI] q|~;i[}.~jV,s=~özI3p#ts`W[ꒈ*_+5%k/T 5)KM/";|[yH] qvv ΟH]J"{j1LꦒzsQ\"oa[h^a:~h]5 e%i ܈jI2= |E,0@;'vfh~פn"],'o vfD  Sg3Z ,+˩8p#:J]Mi(a18{.o3,mҬM%""|0`藤.ʚ4k#c]YAQ=>(3OsXa y$""o v\WRӤ. ƀHEJun3F'mTH2F7_bi5afeۈ j o1?[;wa٘3'bk9L9.-A!1p#"1Q/XgKuz6}ZD 9[iaƴh'Q/LKU _?~LDDDE4nc8"U>>RP+z@8aָ=04={˪~4SsSTccݶ:7"""Z\BzcTp˰ H޹]Bl@/Fnڭ:=HIBYlA4B05zd1IDDVt;%S (Ri5ٟO+Q[>"kcfM6*CDT+hQQáPw=m܊?ᥤ'ct0F?s*HN?LODDILS~h4gFT +65K79hٚ\jtuz[>"kcfE{n5*D6RqI d|Z٢9N^YyzCC,اy+7QT\ ^[\Sc8=/~r'GB(P!WQwL(UwvO"$_C 7W:dd2t"mX 8ur:e~ϻFުYAG?4 nfeBq;^>~prv1ΣvzkSk({Ǭ6ɠ*,@FZ ށ76kYQ%)}xhT*C81`sֳ'S U*KVZ5sb ? {G+!b3areqI ]gR7,_~d(z# n2z]o>; ?7Eū?@%28aTpl?}S/X3uO.&`~&Ϊ5FV'/'"˯ 'F=mpqmd;:w)n FI?kA&6z$DjK8gkvЮm]tj4cP~nB=*B„3-n?XdHMIĚ *|VVyupfn)&B?ƾ Sh?tB6ƶ 1xXD,n&zDDuNQz(*z!ҭ; _, ;/_/"RNjV9 4eY9uǯV=>A`/Wobƭ&Miks }[C䄳I)~$9T-$jԸ^~؂;6 =<Yӑضa5. ]:{=taЛDW/ BBJ%def`Ւyלض+ܦڴ~e .6$ğ%h6J7˿eQݔUa޽bք M֤Y N~{[1x>5b͸p7Lu7kzl۰-6y۹9BfMaxSгmZd]1tz22 72ӱcBj23wx/>}~&3," 4k.#@ Rm%n ._Dd}{ݶSR$*z& Ô;9b3w\ٰMw7'#46+.)^/.)2]AԐʭ?4 {S77uf%%pq s˽PIՙ޼m8rh4BlgW^ԔDۺGœ, \Mك ~yS0͉w; nDD4m+Hϸ!y2t 3hateQ|iMJ99Qmv5[V<鳳>08G vntz2yjΗD#7'K^ڭ} $TVZw AШ1nĉ_FVf؅ċxO&!<)m& ='lЉ0 ޾8u$'cɺn6e߸fr֬ mȱSқuEp70p2{+QP&ç^MC{>hAja#N׬c2rn[:*Q yA -%Ʉ, pKOMV7.hb^O0aE +"jjp?I{"l?ңs[~դY az L,Lz% u_0p2dD=*?lEFTFWy!4T5ytV'ۏAQŒFXt`Vރ d;Vm_wg}!DD[yf{r'G__rg|׳qt>y 5+}:E I)!s(TE׳kWC+=8~8I^!20Mh&祿0?ٻK'K濅YVO_}Px-x]PfjD"fF/L&CZ?^lJ*}P |WcRTt6>`hҬ0l?(!dJmުS*9Y->xCu*쉉ƚbsk] $gDTSbwGgj5ΪReoN(P!z6&|!6ΞA`[/v<~Cp!o!`[= \]1}_a!xّ(̋!okXu'z?QAȝ5tJq5t 2rn ڣIBUT)c@Nu+?g3d}^G^'~MGų'fq^󖭪MdيjJ_.lzzّڀ'/K||3vv|v$2snf^-[Rޜ g6!0(ЫCWEOOZ3w8FBUu=U`fi-@5}Xt-  2?iW}Zǜ^N.Gh4$ϮnMIoVh3\uItNR50(!]/9T3U3i|a)'gurB4l]%23*7"Pco\MУ:\4k*^Ce_*G'-3F sПjPW/cѼe+p;AR5xX5cmyZ69r%SK~٤igCtb'O>.ud'f~}?lp36S_ 1@Yդ;=.93&=/O¶ MbTsH]@]FnmJ٤Uik4XND5pҰ@牡MUX3'b݊nA!0 "D֯ABCI?`n*Zyz std2Z^z{xzaȱ0eܙBXt-B ^sv#b0[*"2 S`IK͉1T2lDro&-x Gz:ARbcj#"p1*DvK *^EmG*{9݄̏y:x(}c(wu+&jPͭ}Zd/=G5%j5TxٵJV*ٚU>уmjyC+깨kxӚnb60SuRjm5_2-%""@OǽªbȈ*GEM:= svcM#"skP[d@FfE V=Jmqv5Lm"T0]HխgUzHW(mDDd[Jj_Xxg3d{=!Uu;QF0hUԗDDT; p8z='=ϬOx]XDb͸S?<ސ`1OiHH]d5bF#u9${wlFc.j nVnypt<9 u)TG)TE K'˱ Эh4A".j nf1JDF>F E8y9Qrw-\ `Y"4ɤ.&xc1HNdž՟J]Ua>x%$'#ypoBꒈ DDд)"=#_~a!?ܜ!wr4k4HHn. rWN/>(Q"vfd]OM{6hҌ!L]s#3ϞD}(T* ,"""EY;QMi(/aO{phA%Q1j0L {0q-cՒyRC,s}3I)IֹeY 0Du[C Ǐ!77.j?O>RT+}#}3WӯNy]4nHk׳q:zt C˖r79Sѥ{ԥYMR]ä.bfEP!S4"*L-8YKլoOΆ"""#"#±}. d #u uM&.@DDD*.Vx\xYRȄ.*ޣԥY ܪ 2#""tA۷""2!0>mj< .J]07+cEDDDغ P\""2L} fMeF־`Ւyc:[-nDDD[q_sX)풻PYS-F#uiDR ! >،Q#/@Ռ&XC!."""2ӕ49]H]޲{wl.l>m0h.UCIБcz99'DD6̽e ̟=oN{ o[RDT.!wuzq'F?1x>1).* wuՅ߳(FDDD$ĤdϗFDDDD7e7/"""=?}NMDDDT1p/s,J܈V15TT7""""հÿI]"U7+cZM}m9{>׷%uDDDDT ܈j63Դt$"""JbV]*vf̚lFjZ: Tw췓RJDDDD͊.p'27H3&nu="""dnVXR"""ZI@C6"""epR+%"""UL߈lڎH]2U7k`A_`FDDdkzܢd̑l""""7+cEDDD(HϴNK]:YP0#""].8^=sߏFRIDDDDV͊8YZUq%y_KpG"jK@8u?iW3.L&G5|J]QJFG1R-n#u)DDDd@khpѧ8t?(/OyV[BVp4ΜG1.REDDT1p]:a]FM.G}{ """R5=#"rK]U.#htI/_WWuϢKhGR@PQK ""ـF㌈R""""9<vpr;Ӗ(Risuk """sYAQe5if|a<̙1ڭ&L)u߱~e `ҵf"""=YAQeشWfU;nDDDDds\ݚbҵCJjnDDDDd !XYc#9!0ypoզJגdjIDDD7""""2=6sr*]UeDDDT1p#"""[.#*,@FZ nDpk~p4T$'#[/@~Cc72qI\87荠.&QV_t< £5:vGKOd2XBUX. =5)~ >60p#"""u=8{ӓX4k* I#E@X![/Dƿ^ipnyϞ:L^LVWdefc:u gW9-YwK3ؼf23͉1(ـ޲ Ì;J<<muܖvĀa[z!WrBk(aԈa>KLfm.'![/ {%"vJ%a[UX n 1vz2{g=b; cuqH)ºtߛ=?lEjLe)۹9P*n &Y:ChwϋC@J¶yV%'뺰}Ide"""= ܈$P&ò%c\T+M*oRnd`*}lYYNΥ\y!ae#"""]]1v ! jXgw4jP/W/-уmj᱇zƎNFq T¶+::׏`aFDDDd#.Z|0bmF:lxт͉_>wT{9Y&_+Q-8_@{aQ^%GDDD 7""""޲&FWӯzbnb[Xhrb9˽iuĽմs1p#"" {88[}8ipPF0QUZڕ$a[~F)Qq.Z]\kGpuk*l=u 4zų'-o1Fh4{=lX """"2AS1x]`Kr$]e2" 'ğ1G+5\'*އ۹9F;;;e {EJDDD6ըL" LNǙGQVDFjJ">`Ξ:D \:;n@XNO ۫уq#3]1zPu!ZEd2Fyv93&b'#5%72ӱ-B<&""".)%"""%:Y}>xsҍ? ]G 7' {wlFrB<̘DK*' +WLkoƿ^ @ӓB݀6TԵU?('UQ`FDDDDJPHx.=PTUȧDB F-lִj?qI\8Td8;ye2>BUKm'L& ""Ç.jFza",]&ͬ TT6̙]bI?*Qq^Uۨo7BEDDTp7""""j:l+Qq;7gN>7 t=;{{ |RJDDDDdKsvcޒ5zCHo [zxJ]20nDDDDDd8vnYBJ|!z q5""zd2ޞ)V6Y&W-.ÇJ]ռK <-ήr |v[Xj?Fd#CRU_Ġ}Pԥi ܈K X~3ΝfF 㞇ER<nDDDD K] YY˖j7"""""""""+ DDDDDDDDDVȊY7"""""""""+bFDDDDDDDDdE ܈1p#"""""""""nDDDDDDDDDVȊY7"""""""""+bFDDDDDDDDdE ܈1p#"""""""""nDDDDDDDDDVȊY7"""""""""+bFDDDDDDDDdE ܈ TT n5_hJTǚvRWADDDRsݾǰLyZs"mDhjr]_ &6"skCj"""uyA"M2jŸVpzN!%ujɩgK@mP"""uw7Oj[wrNET)*Ur+*\Cbh{QU{*K Y*?ITi%%V?%W"%"/IDDDH܊[,u D= )jOyԍ"QV ܈*KVZFTyq""""i(uuI Ν+wf'pIDAT/}MJ]ͫ:u #.^:xnlh6ܛI]ͫk3}B0?%˩%j5.ä3'bSѥ{%ټ|֭XVl+u9DDDT0p;z%O%=CX ڴ@`H*_䍖˷5=óԷf(TEgR'ZjcB=< Dh48G. #"'/'"˯kpx #zA}-ޱ/ ݱqeTK @.b05mnmq *l6pdh 3/琝y wվnmܔz "]3.Ok㌆n>~mFW%%dV!ns^{\x.vv ׳bwſp38G|1o]{V; 6O/=pigdefP@}?AUnh0N݂fg(&NܸvzI9:7F`H;⫘HIHG.>3澪7TڠY<2P{>FB8 ١UFC۹J_x4kQ=Uy]=7VF9YμFhѪY+F.p=+ 6{6צP&{U|WJ%.NX$$݃菷&@QgL_\REzz_AX γ^syv֬EtumM_|hq37;Woۘ 'Mݳ" riIPT] m[֩Es8a;r^@7S "f} >^V¾%j5TN.z <nr93&B˜zUU. WMMIu_"+3CoL2hhp`wػc6_ Sgb[뛪YwÞ3[=ӵi58z`6·z6mTtO%'"""U?E+[jfr?=zU7;PxQh4,:GnN>ٙRqY\ƕ;Q'58oQ,|{AH[@wo|;0%#:(/[ˮ8㾊(Ԭ;S [ظr'n*;WY9dJS 6}2k%2sLnQ^ئw#i +my +%{f̈́m: e2sq_wbH .Nk./z9t:~>dp^ϼ7 P"P/b?yB^7u/ͷ޵Sgc~&2^ec7,Cޞ]yQ6؍za[߰v^V{Ok;L&Z (KC6ujޜ-<zQYByxz *Xr1TX|23*\'9!7~epN]0T6$ K8PS 5%an| Z<<ڭp|RmVɣfߧ^HbЦEM~"6]mA! {77cZB^H+޺ɞGեI3ce~E FF߰pڐk DȓO;wza'sQCoEʻعq?Oi>pFI3WDۿ( _fkzn*t(RŚϾ5xqWvESGbǰQ)bʝxFϣ- z%_s@Fצm^L"WQ`ѰBz}:z<~`Ͽ!]r'9Ľ*Jl=h}{}B0po& }խ{P;ݶHpm]/=.^{jMYnyĽ `ݽ0&6W>G(PazG7 ێN3;{{xxz Rڕr5[T72ӱcHNGrB<ޝnȱ4vHMIĚPTc55Y=|[|]uyxz /^į? ۟ܢZZ-WƔ;T;B05z^ͩ)lA4`tz2ܪm<UV!+ۑíXӬ5!eO 5L>~m }f/y t,6+Rv;W#Q;G1~H ΟJ(0~H!H[7?U:4fs} ´&\1qs-{wF QZ5!L-Jzeg*6z)۲Ga{H6 ~7j6R e2NwKcU4L2@?={+ T8{&uFC e2댾a!mU6l͏z hCœmD Q/ An;q0ݼkxY7NX$ ˃nM}B 68d^.w͊?{YYY/lOzfkM|dBߖ#c4 ~N;SM;.~t0aLVֳ>>^ DxSnл;`|بL&S)pP@zjB+2 ~d_ mUa@9 LDŽ)3ڭED.gWAئ'6sUMi)za ]ǽ&<̀DDDDaVK[.[- `Cesҹ{67AVWImݢ 1crhXjz^FV:tInFOmY0ǯ OafUaOڥ/AgBЇ_FMsF}35Ռ&߷D;VϵnTؖ8] EKa[GgLx;wx5 ۋ6n5:ҷ6nVK]nr?q7_Et,^_-ʼnNSsv} U}- 0.@qKO}(/?􃐛YBOȧL{<}=&+w2G-wfl]0aL<5|Y]벰=`s&&hߩS1y>1̻䄩3b^شfRe~^""""2jȱQORE~AF1q1q%&p(UpV_zM-Ьhǻႏ_Y.V|Y9Uu(T˾fML/?Д۹Js,߷&اaeC9qY[0ūek97Mx.{S7w.F,V[X@)Ob"Yjnd}{GV,z>M2gF4jd4XO/SPN'K4Xl@z/ 4F̉*])'t(;{{ 9Vxd[HMID:@;^c)=Pˣ*,ወpj$XGZ5"my}VWӅmEw2ǀ}~O5t"Q,R Xb°[Xjm[1;|2K̔=ʛMZI|PYEwp㸒^NÎcƇ1`Tp hhby1UsW++r!-T*BоSWtϢ y-/}bewzDDDDE^JbU 4z% &@#NJ{XUf8cWk3]&^x`Hʄ[yeaQ1UR҄ȸ :Ŭ& Q^b}KNJ:Mݰ3y٤^~!b彇X;;x8;*>/ r6@;ԲɥCŽd⡣6=>Y~?ضa5B06jYLVnZUaAõB1z051pPvB`VTxF.&{im牪[ |-M3?[&5i抁{߰pd^GʟWqt?p],wOWQTxG/l9~G{Ud`>/6ڽRG !lyU{Y{S7L2EpG/\j~$.]a!nY\RE h)̍R`m&^Je5mn qO'W7U£toϳ8'gDCq#3W.߅՟7k5OJf ma zm7""" ,Ԥ\ؾuMy L|ǯz~h؟J]-Q~(bgogq;kӭ)Qԭ^nK7ayckiÏFdg$Vc>hXՃ5S>*l3<&:YֽYT2|[y&B[{BJiM)hEhNhW45j15ZM+{Ǭdխ7Zyz ۢЮy#3…ċT$%Ujss?(DoER#"""Ms%W,+'t̡~'|oXՇY^ٕ6mA94J8_3=J{Dd $~M|Le۳'J8 UVM#sۏh燓8~-믚'J{p  \sJ ( cUX Npm ۦVB&rKW>ukڼX+PNU7&=Ox|p#^&+Q`=ehS+j4}DDDDe1p;>yXU=d ,w2ر;ܶu{Mr +?qOD}JԅSlX~ovn!OVw*^y?K{*ZkC],_BnWKJv.>0}ӕZA+KMONz# ._㠰Ҽ5̍.oLx; Ϊ&S` mS[igƥb+;ickS[t;7G815zh4$ğ[ bjIfl޾J{wlĊ,}aKWS6~埼埼oڦV 5% }ןM߅U_8JG2}qz'"""2m$2L7$**ӬS V4E<4Qy۹J$_O;|ysJ\z4i*[y ~oRvktu)Bv-?pN^ֻ~]wYtT`X u?ûC~kSV~ ΟJЛ75d- U=ʾ&W1;/'/'Ww¶?d#e-M݄yRgc8y9QMyxcj^ڵdP"z6_ }^xW[tt<9`ˉڽC ۃvwo.d(R 9~zW>,_aĸ.Q}W}_-5{My۬Fa%?ƼŠ׳א8J_|ӬB5}@Gҭ;tNc>wު~ 4o.7){?v?!Pp5+GXAℹ_toBxt%ֲ:=SArB< _+cڭJSjPT]8z`Bɺj4뼑FߐxLiB R/鳬d2D v!+3ze$BJU GMAVfmXKcuA"""í uANnAx-z\ -GFÕod΍1[z+)! 9(Có>\޵ϟJG¶,zϚ4sŻȊwqi6^F,1nM{GFB vbv교?D =KdvvէG@Cㅰ-4Y}QVسdgR{^7,N?Wv;9b'g8:/m~8{&|[yu\NӟsڴH&@Ϗ!`g7?٤KpokV6D K"P m@4ݏ0z$Ϟ:&S^=~ 'g[ z҉6ZD_cBkӂk%օmaOx]y\p>|(uR9stOp+shfI(*QCJ9 5j4.fh2s1u H(͹g{Q^7U\W2z]ɿmuvű6~R@]5|LJJ+ǜ nY|\RR*uBUdqhQvZSJvfr!X WocʻPʷ;Z(7݋,u纚}$ܸ;UM U2snfv~nrxh^c6BJ*%tnu0rr-?‘||j+Q|Q;{!@;lHvk sVޔ=:t5mm|L_^^_UX\z;|=oy~y7.Uޤ]VMϻec=--"DDD$!nDT)l&p#"-nDDDY7"""""""""+bFDDDDDDDDdE ܈1p#"n7+ 7l&q|QgQVQժƞ5Uc .`m Hp^d9/:/Qul-gWWk/9k)8On#ٺ0KYa,V'Zupm=:fz[p8!ܵ`Fӹ 7u]~Lt9uU77g9Z0jnUU+ܯf?y^n56Nl^WݭZozQu)Fܺo_dz8yC۾tg]WE/vònw˪a]}!NA?XɘMuZ Ϥ_U>U}Xi1VmUu&~C'Nۄi3 n=45&5Ƭ:<OU/ܴ9  a7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp 7 Hp@6R2ޜZ^%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:21+00:00̜.vi{zh؟JmUY\pAQ@BȞucI%9&^ν\.  ބ$8 " NBƒH $$<$8 " NBƒH $$<HH7tO +mp:]dF}SRk+\X,ǩ 99~[h$܄hbsQg޹IvW ۬VfI+MXm5A$ $ux^{5F͠A$ 7RRi $$ЗCCQwIL\5jF@ m)23 ҒC0T-&?J1 &6'!qUV>?P").驝lρۥsw}dddl;M~-PxdJ4> ۫ŏ7c {>IL֩:7##}GUp?C&#bk *5\ҙ8Z6uAjA5*@.GLh$Z3Ut„*IGphB&L&#$In¶U.F}5m]W ϤI(ccq#9nʖ2X3GuoM[WuC&#|\d4H/lgk=e6 h5 BDΖ\ D.襂>Ub*,6'TQdCIZ|}E$|,|CBt4H:V4Ajr  z LFc^f)Tp8]l?TZ @IFoL@@~꯾i|x r#5\ҵ>E:PbIpN"&GS5_-9w75܌үUlaBtG<\Jܹ!Ia_AGK[lO_xێeZٶmǏ'??˗/#8|% : @G9`:jkk`0ViKDDDEEj bQmO$gk'6jFS& ٌ$;0=T1=L޽w QTTĹs(,,ܹs(J kV1 8B6ZjjjBɰaHJJbԩ<BBr@fA2<4>:?o<9}mg2=z4qqqp̙N NO6{6+WVUE֥v9Bff&3n87nO<h4s:Q\\LQQ555B>RTf$5Ia.#pnٗ$p5T۴  2.Cp\dee駟A||<3gW^aĉwý\.'>>x|AO[)4q eZB)$݄~?T-Cs9~ee%6l`T*-[[oEddKєUj\.<\ø{B6Ha[2yP7Ť3b*++ٲe N$u-`5Q*I]B\N\SLTXHpR )))3{eŊ_Wz E–\6хQ-"??m:ΠAnخj9x[$ 6>}:5wSgʾ}h^`Ϟ=<|G mW`5 =1<0&Ke67qL&Ga{ARX.hh|i4?wX.fZl}H%i6w)RX5cXz5j5YYY$&& mW::Ul}<<1m@p:xvT3hpmּ\u;!~O/2" 6裏b28SXƼ\hs{{6j5V7e%x3Ǿ7w AFG $8wTqAeN_2Tk̓c#H=a^/5kְ~vMhhh~WKqT%5 J*M|Zf3=5+%W /خ2e hMM~K5eU&vUrd c%VpjP\ 54m|::jH_s^'_~{nwX*+:$RdgKfQJ(!U;p| 6l@PAÁX._zɂZfd'&L ii }Qu3Ƣ7\.32pZ,B/XlN>ϭFD&iHp/23f`Μ9n?-T`zp@ _'GFhzEٳg:u*DDDx*?^P!tv:>7Bހ\kB̦xx V\)r^*8y@Na2ɠhiVp{j2w\M@V*9Z6kdb{OM[WZ\Hrdr9=ca!bM4篘8Z6uA̦xJJJ())!==]hSngUBaʫ[p5Nܗ!BԣJm޼Gy__ NME5t(NDž <::jd|0Sw|jko+e,Y"$|l|\ ꚬlm+IU1sTi ^'#G 5jЦRIy4brEhn&1,EGh\vvvzHD*p`ב.ZTIE_xUꑂ 4 f75܌үUlaRMw5t477s=mJ l*99X*+=nþ:N]2M$*T*nFp=C ڌ.ӡz.e\ii) Be}}6[ ;=TxH6:ŨAj&z̦\αcǸ"kg4QPA}vv j|fw?<"r92?\ss3AA76 .c[եPAƖ{b;b8}4|! 9NV+ wjæN?*Q'C[sZGGE*yh|`e6ǎkPf+A\ss3i||7=T``dq5 f;}<<1JQΝfěo)-+'ɼ>~\u;!~O/`MSS ׍dv\QZZ*M+bn m[QE@[n >XEU _ҧhUTTD@,r)BpjFԒPmBN/WC9'k R _fSTT['|Em&\HHHO` >@CNߏ-Y<% q:}4T"p:l۶Mh܎.44$H1tRcNLY32ҧh WClǏr!˹1c477 NP__/#l4##[]*:m&ij*9w>>>r>v//9sFh݊.!!W4P_aJm"/QR$66LK/Ν;QT[Nh3݊nذaus) '`V]|@EEE[oXxΜ9piFЦ \bbbk>.'-U$g[QQJT&33MuD6#\5s #q@‘!5&甋tرz[ ʜث`X#,L\wb:9w T7^J6x[ i[ y6GFp z!浕t\.(6QpWq:[> UDd2%.]"*JhojѣL8QhS7c /&fN^4h$u{b[5f3dEDm9rÆ CSS\SS'O㔖t:Yj>g̘ŋZRp8\hjsvM/*Rըemj{TLp\xmO>dBcc# 0@uZr.i3e$D\.ELK+x6C0… ۷/G棏>g)ɘ>}:~-Z؜hLYuvIHtY+":ZeݑN8!]`͚5޸qc>t  .6QTnhu+ U:H6}&/mٲy(*  xg 66Vhs0),k̀x7LAr\0k^dB_hK#6m/f NTh">3^z%Alޝ_R^' 'i@!v(kz~peeeL6MhSOxb^|E9krӗ,$sOL@z{dƍ<#zGՏ3 rrrHKKsv'u-?s< An0f31}Цcq޽c#/_o6]u`jogWE]ZU ?DM nȑWdRexW9vcǎ}*QQLb:bYqlj4p8xwݓq? 0Bʕ+_ʎ;:3͔\nοϘ:0Ϗ)-[п&L )+5k֐ѣ;g0꫼[B"9z(К n:K?w UVzj222gʚkiw_gLH8\j6o#::Yf mhjY|r>[~aƏXVF5k?M|FOZ)Ɉ{yd>vؿ,IrrrXd EEEg S_Vw~Wi)/GDž6,_`v'x3ULٳo^kn80mqbw瓑z Bp;_=0vSg[ZZxx7&$ᵂ=Ae3N/Æ/cBrng1g<󤦦dM%=wn8HPO˜[6S؍FMMȕJE6|dffr M-^![3 cĀ`UK]n&Mw<8گnZ-heee%˖-c_УkpHaK;N /3v=* o…  e܁'8&N^0P\>c\\ׯ'==.Qu:} m К+dʕ+6G*Q/gX?#`>9s_Œ3!FamH2L{9ٺuXND-8C2# 蛻?'3g-Ͷ:f3j5"hoEnn. b@tU>cp9Hݭ+W9sw߉ܖ?)pڵkYn9\ƙr.i\g*3+ f̘]tܔ뛾 _W6nHvv6}E,STpbgxי0aG+;tڞߔ~W^Ͷmؿyf~2 ϸrJÙ6m۷ojicL 6:u\,Sf;*L\4Pko[>e۷/=k׮ͬNN'=[a~-ZDXX~-B[w|F Iq*RzfϞ͞={HOOg޽]Vnf'Yd O?4/"n\]r#gʍL5 ;{3TϘ1c׿EJJ`xat:yy뭷Ϙ1c`k&Mpg)a6o̙3Yj< L=97r9Vr}}d g{rEz)t:^lwgvw`XxWyo+;]U,l3HO~|aU(<ԟSǓy?~S4cq15;w@…w;dffIvv6CG!LJf$yؿ?hZ&OLrr2 $$$0`|nAv^C3e wkvSTTٳg),,ѣl6fΜ̙3/~AxxЧ@ Iptr)8ٳg)--*Htt4JJEHHrd--tЀ`@SQQA~>|8Æ #))T'f3ϟ ٌdBS{76$4<FCHHj8Һ! NXt:l؀_>[\hs$,b,"! q$Jr$܇$8  N8-uuヿHItIp"}$UT('JtIp""pGH*8aUH)W*%yD ш\OnDHa! N\PKC0r{Y"{.W{W!X,JJJl 2 ̣+ȰZ W_|EFEpp0)))3O NdXpu+++nihh`5JuHHX޺u+3fh4ǎҥKl۶MT㺼Ip"z%@i|{'"\v;֚PJ^$8ap袄g"6+Jtmov}?^$5" DJr}^6mڴmx"zIp" 3.]ѣoضc6mQ$)=+zIp"a2aBdovE,X :i"nx~lx-N$Bmm-+W_%cbbP*ؓ'+իoؖ&O,=Ip"| -{7uT^{5އzuɣ5ct;pL@4͒pD` bhtIh$܈$8\Jjg8LM^[O@s m$$%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/images/s2shapeindexva--r7cetx2y1t.png000066400000000000000000000027621524103652300220120ustar00rootroot00000000000000PNG  IHDRy2 cHRMz&u0`:pQ<,PLTE➻瓳펰嗶돰⍯㜺钲时䛹畵搰ᓴ㑲▵䎯ᘶ囹ᘷ旷}VbKGDHtIME YIDATxi[Qa SIqC5R3+\J*Ppλq/lp fcǎ;vرllb"y*;95tf&3{sX3w{Pl67pwHb|,\ 6]#YUҰZJYX&x(ϛu<| 1}X_Hvc3Vhc3 >gj\661t#;r[w\,vN fsp6s}.[lҰf}. ۢEa>3/lp>|ͷ2N7 ΞC&^̱^}9c=9_~.Fc'VYb+oi?(Ml96pXϵT_ya;˦M tC`7>|<2t6?>C ks5}N;焱'%sHaS-QQe}N[rM9E>'u &91>'__Bp9x_PpX>'s|lϱL ,pcb{ZN~a 8Xe 1wlϡZcw˗G* ,vbg믠96HaD9Ӎ~lHǞGa,>7Try9q,>7^s#XSs U۝`g,>׊u$]ϴ)ezWCo;HIO[XF}1iMk,>˭;su,>WŲs5lOk` Vرcǎ;vQ >%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/images/s2shapeindexva--se7sz45xy.png000066400000000000000000000312261524103652300216600ustar00rootroot00000000000000PNG  IHDRy cHRMz&u0`:pQ<bKGDtIME Y1vIDATxyT$Bm  ov6vӴItw2&MlMӹmp/u&xc 6$$txa䱉x0 'awRH߂NdYуXPHZP>Tc1( QHnAr(l!LMbDvUwEjmP'Tc8Ս,U6Dꃧ$H1@=]{AȰq*F,{E ;9P|UJ%@"bLRQ]o !CN׮l) E (?NpIZmpOT @v@ꠇ ѻ'+ŘQ?P 7BBŘ8BePKװ0['b#T')(-m:tAZb(t:!=dZP!yVL`N1rObLQb Z>VL"p k.\i`%\sX>= ;`{Ġp O fY  h cB+A QC VS=\Kb{<= C`UC"a8IXC1V@ X3 {ƈV  ~)4T 9 F-6  &T'V5T@c 1J wΈV[v/or,9(K,C;ap'XEj;k`lwCU4q*/KU%,t#}J(ƍdNbr1fMyhKfCd,TP)9XQ18((+y#o *W 1.Kե%HYQV4TDZN.)XdHblL,2̊*c ζFPNC!" N\5 bB]/BjD y VuP;; \B (E R<=+uW;a0^"BD`;*Dgі`4Pq',^h`EP-_Q=9p=P%q-& +JP.3U8{Y.qHר/rz`Ud髴%ɼ:*+EZNOV.mH&2j!ۿ P+n~[Fܸq>@p,DO1rҥxfV6ai{0@ۯD:GXLkŅSO~Cر.]UjDgrexz /w Z_?z,76w?{o| uX Q*z`_QyhZǏǚ5k0e#}z\x& ?lZɳGN %.n5SX"QӇ|O`;wTdNhA++ƜO\.zzzXUUU0L&Ckw%>cOw~ T;c>z}>;onJT*/s=ZPEUˆ1!W_^HN8yXj#}}|Ǻu0a"s=C(aM_=LLML<jт*g<ӎ]6QXm}Áq#1c|alSD#H'|k׮ʼn'c_| -z@IjT_fN`qp?:L-EQcK-yPS8#4uBc- V\Xy\jRqfM \Ps)TQB"j\H/ *-^Ć*E}@"aVu-v`鄶*p= "u(XdqL X`jpŎc &lj >3^(TQJ*y V MSb(V`tX#+P)TQO,fa` ɾ*_vwE 6T*BAF\EYN7s=NTi :YZ 쯂jт śVPNtlB2% Z B ñq| X7abBKi}npp=NDUpM/@SCB"Lq5p[oz$  |jh` J  UW :)X! WE ,,z^X!N^6<n7:>'s ܗ*E 5bZ8BŪɝ`]`=Bۍ*2FgB!<$s tӈ6 C -HU"}< =(V`u@n7ڷQ%c< .SYQ-"}HEYn =P(TdpR馉a#ByX=@|Ej\Ɓ  D16DS+!!_4 CQ VmvznWVRȰ ֭jtoRߣP!>NIj\k`PPHKcL\` FV m$aGX @N:<8P[װ|n7:*+P KK (TDxѝkXZ7FGE%\i#PHKcӂL\eB.6/T&q=NĠX BHB5u)Y8$%i^&p+ʃnQb5H}\tvj; [&F`P%Pb5"! Ը,6T9*VkXj\isB5t! >z8WO DJB<[vsK`5BƼB5daN>?8„;c$<0NJB<VKqE`5BE%ͥP j`)= MJB< -, UpQ >N҉j6#+XlGP$+y7:"/XBU\8Qb$l,ۍPMkTxn-했 ^XQЅ&/q ~?=XUZZ<nMK`3AsPbd"3&ag^+(T$b0n  ?N+PX@`mńC"&IjТ8l&nCYPRBb"Lo)T$%|5Z6#XLF”)\(V!KgggBE6x% B()TCk D&XZ+Z8Za1רRgϢP* D@tBEU<ipݭYHP*LS l J8lAk7n /*:g6*(Vaŧ'C{_f,2ltvh7v #e6bfl,=]`J̤Ps Ըs,XH)+Pqb&X&u }L˹~M<-T]@K%[ WAŊ#"%jk>(x^<*8WˁvsPS`@i3(TXqo/Xl(T$)q4O[z;Z;-DJ (V Qى!BEHJiipKoGvhS~J1bB'`qb[noBE=2N;tAV`@B#+ 6Qkwwv_QQ&X:n p88G VuCE"d`26>ƭN', ŁJ$ӊw(V<`ݸ'*BH)|~&Z:hT!i(V"$b]tH<Ŋ甲~K{=6B*Ai}6"@~$EIPBxң -!H @<R9)b11G#A,xۋKZc,~] 8W BAa-s札7o=lsp=&Pec~&~)>HVX UD x% 8tVX-}@a%`r&["d2UN,^X@5ZQIdjڠn+~ID^ !}l=vD±HmR9an`Ŋc=@ƪ$X2epbD"h~E[7*hQ8:i /õK,Xq׋-r3*,c, nT!dʐCKp-K}#c+RIᅊ!y)H>H(X$lݨRq#P>R9K7t&:%z|"O-)Ao&X2Eb֍:LVTKp/ S% G(VaEE-4,P1n RHl`B5~L24 /ól3 `-XQ7-{~C$ݨ85GKp/ s}#+(Va„*7[š N hgNIAvVTKp/S}#(XB O˖bQBŠ`hevG/T LϒM4R…bbj-\z&Xr]"`Aő:_{&/Q€bBj]uOC lP#Trt<}2T t&i8T LrX)XD ()O~:E"FɃc:MEV:?B`u''*Qo/Lzb`i#SóP12wޚxl bBU4bD"y rExMg`QƦ#[P1(XAE O'.jQ4RCuE Ut\3 l.4Ж`QCuF)00q V`\D;RФGFzNTs=NTX ۇcnQ2 I`+pNk`l䅊)^溋 X ۇچR`Nl=-A7pJk#(@Vl=H`USb5DLF)0)*g(X3Zۏt`R^F\z6X)XAO':PT "a:W\k`WT1c|",Eˍ;1u|ḞW$½SPbuL&$P!Gz .vc3,z^aWX'OSbu>.E+*=!Dnu_>/NwlB"`(Xںq=@z"``݋buEu}f'a8A|<4,5 HP _M0֞ *(TKBR9+NLO@6@b|n/jPP㑵a$Nn+i3N[Cn ֜۱riL հ M"jNLP _xp b6VwO`ob*Hb1+һZ)THOr=NT+\ Ɠ'c:X1+5Z.H\FLlXsK6!Bd~E"\K6+݃P%p=NT~KZlMDZ"*SXQ-B 16X. VkѹS(T!wXIXϞzX]=mI)4Z81A #{``EZ'vUKPC.6XSSX d UXr"Q։Q4 UXVA* V{{{ օBi*N]\S өS\rQ+ń+XPI` l}&̦.G#p)OQ2!IJ ף4B\K65{unG ^w|6Gkb޼*,$v,{p?Xd>3\p-&|z'f")B>e*FM絵x/Kz 8WpqE8V@f^,_hXT0 v<.'2A||uU\t ?{ |#VTt?,LV >ϣ7oFNNEԬn' !_إá|X!v0_o}ٻHR'!Jr-h&V'`/cĈXv-c{|[·m@,_2t:Ԟ< (\g^x=hWGRr \A6w.ƍXA5ۀvgj:c{w rss5O/KUա?=>WXUl:;0j\2F}}H2т"*4:QsQ%SSP8R+W#c\r~{H?gr"w\pBo}9j!`{W&d"X hut U_YYr`)Ǝ#:p݁BD 1Z ZX+ Z,ʆD&DXu81݁6`F~&_$+^RcI"?eDi3E'|3Ǫ#vq9t]*Qr6`*jRZ ]ǫa9yX1Z6B(Xgg (wr:~gP"&VG7jjB6*PBR{OPVF\8$ n %bBrZ*PB́/NQZFBK ),0=8X8l Mm=cP0vKD5ux+=pjE *1S-{ TXOHgi9< y~2=wCE"`em@K⬑BEX`mDQ~ JU%*ҏH* $gr=NDtˁgiEEʟ`.V}CE)WRdoXJV" W`beyp^%i*PklusP%tl_x+XQam`%麅St ~*BEEL67N6vbMi: H*fȌm{4ڰ U<r7X_zb*Kˡ?t ap'TOLhHC:lz3fRHh1װ =XaƙK*>B&XQ6|h¬B 2  =b*\!| K @PJڼ1*uJ"l n!X` J'EH_Vk4cVQp7) 0)X!feP`#?Xg 4qH cu0!Vb7pr TTtpO("kS Xqgq=ΐfñK*Iip/}X.ǺY* T w4G\2a&LoR1s2o !֛B0 3XC sPHa`\65 >L8m~!kбҙ*Dr94Lꎇ1k.YpeE* Amwdžٙ* h62 YBm5I)DU୙omS 7L$^v7!!v zwF4 ș9=8yYi2r 1n}kP7pR3qfǏqv'ϔRcnvr*p8@ k~^C~JMm~BÄB!CE"{+B!G"{+BHTtػw/NgH/@ss3O3лd+s2 Xjc߾}2  .Dii)ƍxw1yd`Æ She5tƺun:̞=nCq="!QnCaڵXn̙[n_#G /D%AD+aŲe؏W^^xɓ. * b8(3zD">uNF }lnGjjjH6JH0-]=Oॗ^w,\YYYXnokaۡR _Hw?*m6233!F "\T~onnoׯb1V^Ͳ}vܹ۷Ϭ.\x"n݊-[`ǎv // Jl6>@uu5z{{x0j(͛7{ҥKPE_F||W¡C~6mߎEmZw^l6̛7ٌ^{ )))Oضmy!=~rlٲ/~~kш|;(**Bww7@L&lݺ#F/~ T*444wށX,K/G|}6u{EYY~m7~+!!!Fؾ};z),]r_9g̛7.|>{=[~~bz(PaϞ=سgH$‹/2sfof֯_ٳ7nH4w^b+V`;v ---غu+{4 w֭[T*gφ^G}봺"܌xX,߿:6lxm222ꫯu7ꫯ˘>}:N'vڅ_do7}Wxȑxُa˖-v 0,ZV8^/g Z͆1c ;v :YYY~~k4vT*X3f<>& V#Fpm&+l{zz:6l؀7>6+1q3 +Wsy"GTO<]]]+P(`6{*lRd2Y= Ϥ^lp\8zW~/Bb1@{`?w\!sm*233zP(s}뺺gCOOOl6idL&|n3&''#!!?O2(J2h'jLz=ƏS$Yǹs  SHyyyB}}};|0{zhkkcZӧ{JJJp5\zo!EBB>3ONZY Å ?@d ڊgy=pBٳo&y+®OBz ֭Cww7v=} R'_wH"_G}?Op:~Gr9^{5|/ _G&!//L clقO>ݻ &ˤR)|MTUU?^Gbb"4 q̈́|EZZb^ {1//IѣG#== !))܂ T*'୷ނH$BNN}YkƎ~%'G?)B5+B!G"{+B!G"{+B!G"{+B!G"{+B!66S޽%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/images/s2shapeindexva--um6vt6k57ob.png000066400000000000000000000345161524103652300220770ustar00rootroot00000000000000PNG  IHDR-j cHRMz&u0`:pQ<bKGDtIME Y8.IDATx}ɺFqE@I(Z$lx(;jcOٍޙY{w<3;3ȶ$"EH7hͦ( +*<]uLLL`b,c Ĥ41"ML)@.b Ĥ41"ML)@.blPk BQk*FM֨꒎e tPu UV+X [ӂivX=v^A [6EtA&]lȕe Պmrp:8lV6 ͊ 8l ` 8dECudEE5$ECRTJ J2QAS5~;>;}Nvb!A_3)6":kk::\M ul/qqٰY;{PTj]\($ʢDIPT~'CυnzL]l5$D%pI/"w{'*rlNRPn;=az`ą`e! YȽ5d JK,&pbUt HXCl(L]05i3x;6 ^ E<\_vJ]RIE9thL xq{e L6Bչ2s"~^">YHdE*bA7G'ݾTn-ExѨdEc9Ua%Utqho;)ǐ,J|6SdvMd8at @erTȞa/  :}YWXvDmYXJVXH zbj2?gvʹyM`b0pL:*skE68{(Ԡ)D0Jλ7rTk:{B EݾtN7zT¦:Zʃ<~W3z6ψϜ+5ox;f,7+;R< ?sQgFs~OgʌL;^ihdEcvr‹b<ogB+toW2"պ̝{>OeU;ynW80HK2ɜ͹,SC.^9yMZ.$E~y!C$fxq{!C\b승}Im+*G̺^&qA^^>܇);>U̖d~i&$xP3ѧ(w,̮ۗce-yXCOoTUfO587mz<͔EKLHoI{Z{bl_޳j\FR~XOIW !Fݾ.0R`1YOٜaO pf Qgd^lgHv//L|OO4dDwr`_/)zFo_28.YNf[j &tڱn_Ζ :bTQԾYDmHdUҝ$?:. Pt~~>EQ8&Et.KsaoT -@E4 퍙&[Bu.$qOİ"ʰWj:?$qS|&M`N~v>v1u5ML4 ӐgShKz$//)VuN싛36qtu~q1[[$ 'mɎ'I~}=|Oģ7&-j8?:+vr~pfʅE3Ϸt]!E(ӐT 6v~J/ QN, v j 52jRUnrlꒆ,kv^'!ѐ|}ɽq޸3~weQz#S1+E"k*C}N= G76ZVt2%l"/A|=ܮy~0.vUN(ezl)DU.Hjpd܃R\+sqDݾUC X!w3+O~$ލ'̈,&J,J+-H!%n߮![-ݫ9e+_Uu~~>ɾi9bvv}Q?y]եD*Q%dUCQ5V 6A$iL(/=sau&Br:hȪjn8zO/nd_]LWw&51w#O$~*f5ET&0dώia ՆJ"/2e20N)S؈; xmdK5MTMg%Ua)Y!F] xtobC%Qp%@X,sr|Cp5JtE*q9On? uX^s׋|ʗz~q7R  5ne'2*|vwɾpOvs |)Uk{Pt۫L 9쪦so1ZKBV|/.d5`r8)p`;9;K86jDgW\+/{{wZZᵡOma½ngW|xcU_>:z"vv<尢(*V $~жL^a*պܵ{ C^vYm`r~eIXu_tʟ!RF{lvHoT;"NVE v`ש=B^V{f\r~x;Ϟ\TMg%]N7.gwoKo\[ tEpzoT 05[ p.QCRz s<$\ ^XÛ2m7.ex-k6mc $w EL3&{\)[15fA4Ȕe~soM޽#[Q9ۅ]Jpƾ-ELIf~jD6d M*VvK䬤j:Y >/pl`kң5A`wZj5]K[e=MY5~77f=Qeh:\Qo=Vs5a#*gOT~%Ȭ:u%m"nnU[Zs5rX^(s Gkj~F^\W2,,]tt7.e7W(U"Sc8Fֲ`rCXuܮm ,^Υ5i~̕v,mA%Ecn]d4KV2b4t/Tn~v E5WjMoaucΝ*=2^֐w譺#>XzQv^'WtƶRM'׽XDnӹԙfKN<=ؠUv+; H9="+RlLTFw(Tn9!G9w+w,T7އXWHkeeJLM {mrΞh-!2*eQo'!PkhdAg$o x4xrXX'~kNO%yJ?:ݞ߲!kIA t/jQWD\Y0{"5|mYٶ- V9?ktEpthvsٲͅ WxZZL EwjExc7vy?L/pxH/UMYԹ6WaBdr8+.Irjˁm7۶n1Yd.K -?KȱڱSC;/u8w;1X Pûy80si'],nso¯fɖzb$ =lK9{lİItis$]{I\/,nu(L4=\7dA9{9nQ+n~"@x{tQ⽛y5w"‘m]/ލH%s_4ֶK6|Pl|#mfD~i MxI?cQ-deu#GzᲝvG&슻8:-WYLչ6_&Ub;=,')MG ;W+u%s7d*<{=ʢۉo[*w,L*//Րdhȁǹغ̩Ueban0U{!@a5eeaE*k 񸬸t}c.6T ]/ so1ϷxE+ x`YXsoʞ2U>o\ʐu^<"aKPXK INAiK*4$ iæq9 Ӿhr>Oo.TNnDXj:m: !:L8`yÎ"oP(D#5]mKfD/?nQalحͽN^k}ÅźrRf8{0ĵ52%8xP[Vɲ\A"|aE\H XL;Ty/shOCtINPUZv{^Sf hmY4_6%E#99ޞDA#>W6s+N=tjODJ`}K` \IUtfฏjJwŸ=[ӑ*N3mނ*2V,8J "G;Swxd:w\I sdV7%]4ab(5YߔS%Xe/5o$/3q1ρ_{ߝ0$W6֋K6:(@M Qvoyd͝zm$JB&JnnA77|Φga%X{ڸ͖c !=zV-2xݒ6"~l+`"I! ЕE:\rl0^b0ffNe΋&i8u*v@ë_vфURUۡ0s3X-ŽRSp9 t S\U3\9$m؄X){/;e)ݠ?lzn ,;k0* vp;M=[_Ex7I; 4"7̮heJ2~ZU6 G, s-ۆ^@onA7 unܙ0IȕdpXef<Z-}'_T6<Nvܞ:5"A!πNQjk Gmkswե CQϯ2Ч2пkse9aRkbvַuW@~/zݽs-GcUd ~s}ss 2%!Ηp,O,0  0=+Y'4]+YSUŘ_!Z"~}5\y%hȐO͊DNtˏmhcq?`ܭ|fw'Hf^î5 U&>o͠V.- PUuþu696Շe۫DB>ev ۷W6h-0"rt:Z,n=Ğ*$wEp58t+"-`h|TpX coÕ%gԋ.kJ { bh&Du,*.3Xt>Gtk\/qq3 ~^YJd&;r39f |Lrc̅/ga5hE@k"e=!@¡̯9oF4ﱂJYTI6ba/k2dd2's ѠNJmߤ Q) yy~Z ̨Ec;/BAX, @6\5͎"ALit};G" LC hl= ʊ ?z~[Ї5>%vٷKblk&̻KGvƾ㷠bC| w<3\+ܣt[ٲ-eC% &:#Ol >'g*nDzfavHhm7`A yqZyq_~޹㓛>0^C4K "k:IVN~^W oa/ԨZM76g<\x`#3u-~v3q)`MӛȖj -2i5WgnK|_Fn?0\"ɦ$ {K^h _dݾEuMltXw7R h|0ԲuYo 2gS[@H˟^=mExxawc E- !uk;fDm*9GƬ7z]|p 9Y3lM$Yl [ht\KW8p4r tDF2h|/stZ[~$nbDޖw[ N`rr-|(fn:y`#n  ^W0n ɀ+` l^5(̀&@:=w,vY46&Z;E& vVb1$Vr)рJx onm[`kfuI!luXI&o]>38o|۬K޸a,cQ骦S 4&\ѾVNܠ?h=a>ͅ v֕,hhc5 eFFC:NˡxzAjM\hj Aaq8t*.F48,p}La gɕض-֫drMX3{b:am[[GqsBΞ0\ɕ\. .Y.ulYA'=`(vtXK[_u ]+S5ĺJ(aZ 8_skּ3u޿ 9!19gm[=rcn9:~OațW2Kc<ĞbUa>Y\ $OLq<\vp}JȄw??_YLչ6_ZWxrK:?$ű=Q|nc 5^ڷ=+Aכ[:o#MuvLΕ)u8щ\/ }H`{@"Yd^:^e/hHn3ʔ$޻g>Q{'"u̹ynI]R*Ʒٖ'IncqN+d.K xX+koXLxx:|p;ϝ9]7* 梇c>>nɖWݼrckgBE9r{cx]\eR?~a{gm R˳"'ǻ|-3Vj12tQbXS][{Ey5lVcPQͱ ݙW*$ْ̱)??b'i:K:*'D&GBL x2&9ˁw-2n裐Ud\rU&t542e w[o Tw~NGƿoj]C@u"n]bMP{ zR4޹ml[~KȪFEII{ՂmGQ5N5e++:[+pF,ݤ~"k-k؛$߼ƙX-aqI,&ˈ5?=]D֘_j!w12 q;m,yP[` =}w sP[8?nhzN|*ЊqGw=5!S#+_U* ua1,w/ql,'* ޯ&j*r. a09f)mLfXT98X ]~WuՔ{V-ZYMZ_ªCۜ۷^2k*+ C;x?JҸ㢶J\c"-s^:6u nwGRއRcn%>rG>nPBϴJZ=&W2^1,'+niLJ47ݔDhdže#_{Lo!pńʾ/1UK7Jn/Vs:Oɗ.+6wJ4,4Wc:?2c>Y"kO%U}N2}/S^=.Ƣ.Ƣ. "Hȴ8霝H_>d,GfYN8ڂZ88g-#>N3q+ʫ(]j域#}MMr?;;܊/{P]2%+Cm8A@AV4ֲ5ۦ%hoGz;,Ի0~R~+j[=}&Lv~3(qzoee@,$vl9uAkMv "PQgZ9/=bﰇZ+*: -* Dg[+vib?WR4l m4~Pz,7[n u>^#b֢Ca~ȋZ[Rq6JtzxZ1oMjF*~9j]P7ֳUГps>:C:W39abs)%QBíut®xWry0rt:u`7dm(Vu^hqVxq_L,C)+^nټ-XXJ^H|YR]ֲ tM߱qѶsȃw`х% U\eB~k~c-hA8-0ho'3&➮X Ƌy5>[ޘ%j̮yhcm`˴ML3 {/pg!˙}'N (Jϖy]vyxYopqvs*C~&حj$Pygm{UMl~sYaCy~ rj$mX,a Gacؿᘏ;Ky82nٺK+) nDԼn;RH&~u9K4`煽AƢ'2%Kϕ <`Ǡ[@R4n/GzǶ6ïfITNoMTDTDŲT98ꒆPI$Ru\+c#Ij̯W}19;益,QTbZAd!|x}cWs6FL'?L XI׷sk,un>pd [èB [jt_\LSPU4G&[q40^BQ^jC#-ro)OY܂3@$bz8.K\h0J3u7kIdELWw' WyrDAn]HEnSb#QbOQz':\I0w"x]}nGB]FCVYʓ̉pd_ʵ2o+&LFJrY/=ճpWP;OBIE[/2r25f$?h=1IF(`F``HDN\67/u74dU#q9f* .I^1Ԃ;x&KYޱN +*NގϫSzߵuo~ce|6S\ T"X?'Sc}!v:t7ٳ&CUu.Mwc(ڱ~Bv.͘"49s~LC3N?O#p^ M)n? M,©}qlftkP5K3IB`lA6򿼘&YP8?n(Lj|v'H?07yjqz/!.$;cƋv> %>)pj_Yf .O}AN,$zNWD~y)iY' g eГX5/$c2=sl [N7c {s7Գ }D-33qA ?}1ݻ l߾c.Qve6y2%QL=#n^=g4Óynrkr 31hz<̯].>}9- @,`pl*f>%4dhʏu@Uo9_ax𴳖ra}^9yܞjnk lvMȧJMBMQQz4 τaý+2256AV5f򬦫?ȩiaZ3#M s7 ̮L{jiDufWqd7Ϝ7Is-O0=bg C:e*,[yhx,xfJ7s*ŒBl+ɜȽ<.ˇLğVy\ƹ[yu#QS-AuVVxu8̮g\x +:)V>av"+K B^g꽖vb 1 .+soPz\Rzƾ 0S?6n.T>WFFbF^g+Z$Jr82.3lSMsak"~/}gMV4ֳUֳU CO1ԡ^6UU,$k]"a7.G6nZC!̋du&.`Af1C$EzD B4&z~Fu҅\ EVwg PS-D!o QcnF\'s ]QlH*r|A\Xr19feI[)6::+K+:v@q:xx\ץʪFP%JUJM(J F\G s[6b Ô D`-6( > ӎnYp?͊"`  MjF[Uu4MGRT$EC7[U(ITj h@N4$?9{s;1tp3cuPDWQV-q}BʝiQ!6YB$q^{i-juٕe!y YJ{)l~TIf>cb>GI7cKf1]DyJקrcfAKkOsă@)}ҭ"o_Y9s-(mهiwU&Le1 غϮ~?a1#0XZ *zZF)WڽCb%PL$Xxu @ycT,ݙ,ma' uz:'¼ DFҤr%6l u}xynω_nogV4pЦ(]?n-d͐ʗ``G,\'e ֍4>޶mQQ:w^EJ˟M.&ӧI:MqS7Ч"3if2 u89D[iuPU" +dizm?L7k3aA*d:'%<3Ho[7fqc{v>rKKFܯAy6L,).'kki "W@tHHV?\\J~iO2k1J_ttHO/d90}"ԅ$|+)J`3Y\/O}А՗0#y'*ӄ 7SDv=,ԅ"#&\ ڣ^6vE9>Z-~ nIO΢OZscF/ڻK[WByn_o%6FٷRױY՗%˶ncM8ŌBox{71!Z 4MmmV_dp޽^ ]I`8̂f% C0Od|)*.}c+C~,ngLAxu ef?;6`U#}[}r6EUCۺ"sx{ՙ9J&ԘSWS<{6-Q/Y}J ;TtN |)٢՗-4lk%d#;VbX!J=IqѝWI~lB*CaÖ?&gs+mQej РaQJ|id[;Mm9-](˗~)օ{&wٹʝ/ 4^R4!/, 0 _}B*CR6+`K!s cyDvю҅ xꗥ%N Q{ _9a5&/S1nigu9$y+DPXGq;mN"W''L  TFݔ|KbfK%$Oe]6=1MF+?BuY[FoLsJ;xk(0mSbwPL)n{$ q9+3($TO])NHqpG^rh]bu) %w5 3bEjj7a^ wv~a#$!2OLPHf(mڴf/?|mVtBUe-CFLoUKi^pMv9凯Mrj޾YAD~ıc;_#ubb:Mե,˦P{r*/rZ[qQ}ʵkVRגoAqGwq7(@*n~#Oxoo1Qw& +NLkwa ltL|0Nhl}jtr^?Y1v*c+we8mq@39wgcV#4DȏͰk摯T~a!&&P㉺+I5xL͔ \-klZ]NY]./91v"7Sq.92v4'aBlɏO<;_.uj|NK) ƞV~w6t\.G͆K7ju)egt `:9M֮&X[3yv T󼁪8DBt珤̠h;.Z">zZdL?֬|.naF܈aw~RjZba{"kV"ԹJK`S1vl妽gLAo$5ʕWի0M^ڛVRAtAVt8vҎ ە/qenn,.GS5gGҤVmڎ#$Ew! Y +_dKoU0`P+r|R ́rեԔo8 ܺa5zڃ86]NZ]P,s]7ũYnRPwauѝ/)̠L4Xlh csb2kpt5 (ubmn޴p8C+_t9oޜC-C-4'U.ͱurË׹ i .2m/\XXa۳qGq6|*uo@"uٕo7جbu)B,EO\Iqho^#0ǭ.2,iC{.rv%]K͒0 }+ցf轛1LPFF. ǎc8%acWV"ԁi‹o3n[cwA65qV٤fu)Bz_KTLZ]JU%qL0.-}*|ydڅ5޶TucVQ5Z,25IinKI]-ԢqqpU WSF=.z6S,f t^ִBJg0fd< Iv=[] Z]JMRiJ_q:l9w+muB {7SuqB.N,^DVHdC$<)!۱?I<6X]Ί%xҶ}NեԔa8B6dE>HXz {8uyC!Įua^M.pdWG~p2ݸ;>݊iNc,|78K Ӥ#6wŔGL/M>j-⋤G.r ͡Cxb0˝R ZO#?K(OҳV_`/;7!c6+]"z7A`{v>C$q^HFZDi硺:H9Jax}|UFoyn@e{x\ w ߣh~x|%!iDYY;x^[PNޢ} |+~lMz,{M7-$y؋/qQwK,3\Ixw# &%^ڙM# w*\{WةG:ҽ yx/٩KmIAw^J&EۼRN7W-,MhyQ}9ȥ8b*[ ]-K9CB9I{$ OEd=YJqKH'0]W3XtS!/%^[߯7[o4s޿vA7la>::߻A#7phg"2 o){I8Ɠ܋H%;JqctK5wbw3޿7|7aVla~u\yᒾ+;Z>WalvlGB0ś+W ;В)Γ'N`ni}!d|C~}m72Y9&C+-Q/wgUԂaKP 8d2,a^*ܞ] sog4w=[R;MB?e$N)d_Gou)UǰK3~-nnLrOw.#eȌB$X<ӝ?$U Z P>Rt/~E^OvRxubwn.WB ~!rTH꧉擑W-'27&׹ -DV, Z!EIuj|ѠP4an1#wO Cx2n-8q:߃,a~mB !+к^ls߆"6iPemXx8_]yUեL~~ ~B~~Gm#&KoizpsEdIP`&1HJe׎eq;d|A0Yi dZTtԂ$sEvA[Eg&wշ&^sɭi]H5>ry6C?1$SEip''OLੁ_ Q 3i$0 7NK4o?Mp{~Yv-#595`z>O&(>hpzDmKw,']von612pNSf [{TjW5w3yB0M\kD{V@͹"PK8>>dU,z&jÓϐեv$u3[J4+WQs%~9v>yMA``b[C;-I×>-a~fэ]Ss%ω3Ce-Bg?tMg?x6DG'ObƬ!^)r1.0:k|{xK<ԆIنF6w'Ht~tY)G:^[%o`ecJDӽ囄Bݸ?$1ri!_Q{`68~O]f\VG]yT0RX eosp? "AgOͩ =0Ͳnbv|p+.~9T]Swb*Ѱ&e\,z7 7M܏ ]wbi.*w17d*.[=K!^3֢ۇC Mjx/OC W`)U;7ʲAښ|"בK3[dl"o,C62/Z]6۫y)%{ZmwAL0_a/jC6K芸k ~rbw4R2:!w>,\L\Aw #I@a)da.ɁkH5\I|hNNOv '0vLW^0䌻EiJ$ < r1 v^U:&r'}@ )fVZug>nvK^Y+Kj9^ZܙNLE{wdK,+W6,qMT7̕$QNLpDd7 ݳw{|ջYQ)ņɚf<.]Qx..<"GXUk3-4e+ F G ygNډ魍@li?MZ|ibϺ!~^viV)pⵋ iV|P5la0hrTˬW־ӱo&[pqf7\dS8'+lKh[X}yKǘ1Ƕǥ-auiU U $oyJ)21 3  kn ~U%I"[B.\C43Liˆ/MMC3?Ɵ!rњ+ABӰiڮdǸ]|u;8º\ilzije6x7A߹fgGnLoq?C^J_0.K .uKk$4f"<;S|Cf tz6KEԭMI?Ľ1W?Cn-xӷwTu&oNa&HZV泩}9jy+"47S" ON͕qg`m+X{厸:FSmh$tRj.arV lr#S[쵪0Ofpzrh){|H0ROU}>Re٢g_1ۅݏ%Ƭ.nʦa"Wp6ZBN ♕ZՊ<_q5dG}uoL F( ScȻ>mu>;O>;Ȯ\'O|tzE"F)n7ZѺ$ېeWşO௟.;F[Nm;O?CH+s^˄z'PO|H;]u/'ig!CH;G#{!^x{o!^US.cl7v\ѡT/NFWŢK֐ek)Q# ÔЩ+Gt:*)MKv"kKr73MvW6h٣zQA)6wPcU n=nJ.}GPzDשݏ.+OXYz*Ij9a /S;h,v{sW;RYl$2 ;ϊᔺy9N|Dw#G* Ȳ^0MhEW>ransx)x;G.Yt/#4 t8axp:L0maL.j`>2~F)Ob ]?-YeqI8NNf'f xZN}ne5Q;9U cϒ+&.+D=N\ο(Z5N1:Ho`R7v0H8..IaV'FU;WgEa."^ʓ%pQB_ƴQߜgl9)ZC8\hq=ӧ|\z 4DU晗tw2|c@0K?MFc‹St2nMnqmY}t3Ƶī\Kb8(:z:$YVc3|_MĿwP+SmlFBKyo0qۤ,Jk( rJ\ ,]>z_s571^'L7jD,aVndw]QgpHh SW@T*;Mz{ Jkl{]_AF7)\><-#+1k\Kf[ݾa/]xn)!C߼9褯սXQ{64EӆjRcz"x`/Q/'|_Wdh3ߙeS7p>}\ƕqE"TW\Yo&*ʗ8 ]lSSqèM_Ů[?>[?Yc1/%`{RDcY]F]mUBd1]XMM`8Q\>Xx>Kg-ey.JL(R1Mr e V70m++Ivq=Umh7?MPpYD,x7UسFx|q>1C]>>3T2+sI&va£}8ĿŮAy>oy3kV}[hwD/n̩wXbz Qbu,&@Sf]M5E6~qWo W-(o4;mѾͼ6ɼ6is-$!ˬ9uѴLGDtە7wmh utPrY؆,dS5f {3ÆW8r۝;]#i/ }ο#/h31"uw2񚃴]UYJ.Xoan'8D6q먊\&I0%$GE3hM_%gg.r^8!}!i9$/y񀽛m?ECc& 5KWK.rk,a=[.LR15FjJ6k/T3m_^lwpMTw+;؞D3OD:O\\xlifm}kݢPykZb<TDSqy;*1Qw(y}fC|r5ItKOf j-}Ķ͈Wyb}9\I`k^ la2BbMatp^sghSun13㔼"QxwWf]Z(#|lv3741HBzLG-+D 9AMkN{ϓw&THZ}=kRP瘽3GHA.hu$mC><;dbӨGɃ9F'9?˔2buYkr#yvU02) .7U)?ୟŮ<}-ÆC֌[][GY }ί7q>~?M|.C=S3N3P.]Ol|BG6qRv=Rό7Y.C|v=E_?h:ΗHH!z_! ub;@(UtFLdac>`=,enL1Yl7\2a+O]M3p0liN7&jvK$$}ί~Y&SD{YH)ykfPykNf\bߦ2f}$9{-?G{-rSohdJOF8Uu&Kz@$p>v+)+؞D\2.1eYsgngAvQanܷDrZn[?ffd>Ds(dhBnQ'ڭ'! ~4Y[;Nȶ03UPyK[{|-,.׽Q4$kfEBky%OD\ϱY_o;2=C=8Fi$$f:]x]u>Pye v/iBQ@=Or5nE fo7 7٫FW$q6Hw~? m>+CܯHq-d#,an /v-L3c?0]Rύ4D.͆ %)5Օ/|2LB ;C}~i54mP fT6u0_ʶk ;P/̜̿6I/qJ1MxqpH}LW0?+q6?NMZj9] 1:ZA=HɹPJ[Z.ec*~3Oggw~Pq9>̅Wi}Y=3 lu>jKüP4~}vwq=8%=;'4v`s7ό~b@s%B7[j烜4۝^zPf.3>$i?G~Qgβîھ"TVsqRlmϓK wnS2 ޣ̀%$T|IvKLLRqLJHf}Ai^拜4?}MYEw5uckфZ[ GVWRZ7#MP9?p;-?-6gowr+?$#%}Gd'.nU +cy]͹ufa``+a6D[]JUϥ)tD LX]JFxѕ?ƣasg!+pu,g`aj&`+9fhr+aiM5~w^,>wGh Ӄթ0w;e>w 7{\وy史h\ 5MpsN7.Gc5manW(9 =v~{"i<-! kTsacCvGsy~47$cE`Pa'reQ1N.]M9'v77&iBRdjGM;O }# ZAllyمsvv+/ ʗC`p܅t޼6˟=I(G͆9e㯟hDx;3ӄ$bˊm#Kk3 W6!OM9,m6G&W5Qogxe꾕$8B51M0; s{y,9du9roI1V[H6]ݹi.;›WfpXCeR }5ѝJo]!mak0hŧ۹z7 ko) ՞յÏ)R;WEN^dgl4T|v1-8Zab$YZrҒ_H8ma.k5\L;B׫?=+WMzcwӼ}}C&Ԁ s젿HfscTaCː`]da*٢&F昊ҳlhDаa7ɞMumr\L1(N~JUγ"/Nq?Eឆ%^vfR\C+3uZ7$YZwų8BV1cE9"Nl^+0(⋈n m[|1Y^ .ߚx>ʞ1>.ԦuŅg22(l|6htٹ"Vr;TV S_D'Mn/Sj] >3WgbyymC-\k)a'A>Uz5a/H45tDgu o]u  z9q~5w,1y뉡L]\{覲N\DQTlrn0.7$ '.NZMg(F0s9-X!0Hp B|uUSiZF6Mڥ$«^:ΦJ+ium8[\zDt7HYD@6_s LUl޼ٺq_;k'q'N*ǚ/KC܍?E;qhV\q8MF^k&cS F& rh8])94 _\@WsdNq%v I1)l[?&5MOsN6O툊!|IJ=@g!`&? "$3qG5{j[ӄx)B팊9BasFwF3NMl+zM3 M7<:nN,tH0)Ņ$|ҹǯ&6=/n|}nsbj^rq[p<t];Bcal7G\쥷=LvJ[_.0JY"O<5.F43TuCywnxfI_{cqyT] |# ;?ULҌfi;`SW=VMqvX@w樏֐I0Qnf^Lv@p"Ћ&S2>txN-219P2`wUQJ\qNdHWְIhJoF-Cކʘϔz;;<.\!mn"T,ck&/ ")7Rn#^Zxm>:w6NLb7rL^ȒhSu <m. ¼3 gTFgs2=n:B]םبhX@7)DBezH{^6{i!AX 5h6qwNcbAer>dJsFn!\:Pm{ I]HT˲p/|ȫ^p=Q(B@A(Wh9+ZE -"zCBˡ^PDr(3BSDSCQ":ժ] QDQ!s|IZE ԎNYG؊x8{#F5ReV\YJ3d&jH*lj&7BQ})'G kNZpuKG}btA>;fC+r⠅1gZ7P<{{y}ڍJ XXשySwf)d^P؆S?~8mݼrŀ/^|ԡ*vHVJ"RCz$s+ ./y枡}%Qd͗' WXۤgWk,wpɡa;猏ŭ/\ZJŐkG]h:S|x!HUxP`N>όhP1#G̮6^ZSBm3aihhDWã=+>`bЎ$NIrۏX*'d1Оz&tkV{uRߦ,iJѿQ"}k#pjbE _`7hx ][yrq1N(QdbrsȆ/>" ̘usqn,F=t_dk4M%@,ǙQA]Ͳ04mϷ}C}NAR10Q7Zm'&&H27&'F, ;^ Bflk .-^E7w35Ӛu=M#HHOͮM |3A3FIq%BU%&24J/'89Dc*[ /]vX$֩ARr&6 6i- &ez!{Gy-Ub\7^m=ckP<{~ N)"pM`"˄C][,k %~-L:A_[Mpvg4^!XS8LB])fozR|r%‰Nڴn,GLuR=L=2XEҬ\]L3sӐ裩?x80&.oYފ} p2 lSthÆwD_*6 ;YFN3G ;?uV(B0OddjSLd'O<{!u(Y.֌i_3Ʌ|f F(I&P7GX(+/meͅ 'hoH*P_롣]뼑1[ \ZL:oVpںqں>`CJ$W#w c$tiԆt&&IUn׭A2#{fkY?/i6gf=x C[OoSW(goz+JѨ8ZCHYވe86buk^7џ kֽ_M$[:d9}ڇ'/OE7=bO^p7찌>*pBg:jdGeGS>nh65}$~1cDBN|7]MHg ,oDe86D~6Fa!mZO0lKQqh@sڇ.fhS"utЦ.jnE_!䂇tߜ03$8_FQ7&}*[`y37az\Ϗd0?̎E/y?fY Xa%_99wTJ4eNߋ$9NEQtbs}ދ @9wTJ4ez%Mǭ43:tPmM nGLqr+݌̉R_DQ$V/eoUϸGuuf/^맅WݠϬqa[ VXb㽲(ªTKw[Kmk,v>lO.N 艦M ݦWo7طhz͕YvtM4pBi~> :t}Fm|:gԡC[K﨔H2Uo^nDb.fG+XW7 b[KT{7Z9?NK{]$ܽ;x3؍ m._d~%?LݠWw[V5hBjlʪ/ݤ{jo~ ؘ+A>ڭ?av$Z5?~Qdf^~;%Yg[HldjXv&13n{7 5Y-7teo:۵ lu9Y?e v$Ml$Xqՠ'[v~Z?DE?%o\~`, *0UقpśT[BV%&zTMOs͆.-"g{6ŒJ˷|9m:,6s5I=zk_Tx4u)hoSK}rrnXJp<)\~)ql!KoɉADyѮa'3EK/mmmi! b+!B o[?gϲk^R(b_CMѰiN_K+rn /̕ :Ooj*ǕWȀHYOS`NwE n._m?7Wxo^zcK+/%:"8jnRa7;a$-%jVi HpwcW>b j /r})HV({rXe~}QɥMnsa36]raFq\ 39u7i|Λ \D0!Ig%\=:F:F: 5,Rk5$=@./~3{{+nD,x^TzXOqvc_mIg B4x65#}] ; [B|q5;IW=+ 5q|T^RR3ؓWDb)@,K(!`w0d==ʗqJI>f)T6R6;ڱ_3+ŒH8%ed{:1Yv͊&z:-# (,y,mF9ݷ^h*z̺BH(f3Wh40t vuOrHM`+`75oM$eX}?Rb9â(ep݆" g)Dn{bezГ$4d A.x9n%_OBEM@)U7V*XPD_!akIStipwW}T좇wO4g3JD6BYSXMƀMM[~x*Dž/{EV(Ţ_k)iNz8]%,C剢o/#ן(1\WWym]X _=?xֆN4+olt92bȈxze?%`nݣoHf7))H < s+IXM{ Y r=V-PVmF})J,z3\\L8 ;<|O/y/o乪$%%$1w'$ ^#֝,Fh+ۈK"z bNU~SU._+'<E2#%[Jpa1IwAb^׏f#rPD/SJ 4ēEF Ol' ?Rj矀"&8e'041oΑ9Ѥ77|R.RQ$7bpQUz,o-ِR7!م bn^4loJQDr(nGPDr(Wh9+ZE -"zCBˡ^|\%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/images/s2shapeindexva--xkf0e7kq4ae.png000066400000000000000000000261751524103652300221140ustar00rootroot00000000000000PNG  IHDRNIa cHRMz&u0`:pQ<bKGDtIME Y+]IDATx{yICԠdk˲d'qqӦq:Ns˹ιmF4M'òc[=(JEj'@==?@ְ$  O6E/o<~[RUUEAș PiDAȓ yS!O"p INA<)'8A$ Btaz)ߟut R_ jbYvHܟL_/If=8+\4!?Hԗ$nU o`.MKӻcAK gh0tw_V+񓏇BԾ*l{=H^Nono~w0KRaV]lвيըʬcܗ[{ٴy BY7][g  xOުv;hdc1}DtO"ᵍu;Tk\,i>u@#Wd2 e,$g D(oڂ͜=ÐH1&itZ-+,>5?]j !b^N\iaa2 # z(ۯjۨh#b.yŒN&LiI?u赏NVFנرiXw0<Gc'/XdeQIBM9ݟn;ٱ{&9tC$.v᫈YAz"ȲŠ6S&Ij:Vk^lᇯRm#MaBd2 'E{Z#=4sg/ƨJUGф6d?;2b"-bɬ]h6UKAexEG{ץfw.pp򆟟f_>Pޒi_(E(.2idZ%)Zz N¨`5jp ~XhO$3l]Z Lq)EQّ1u1Mo4Mj=ND#W|TttQmӗ $SL33 5vU:^&NK2N+dTZ! Q]O0"OeuZxVL] qg,ww5M>>ndcCQT. s l[VN'V*{&ٽ1XZ#u&\6vKD*;J18_!u&6.baF~ge(R׏ݝWO[HwCc7_nÓI^t`sٍ>(;iض& M}?]w(NeFciϳF|YuH*~<Ɍ=4?юN;G4_0 q|pi@/Jeu`[QOUф6õO4M`lwW\~k"p@4Ϗ?LOFYlaC Oge]3~ W%9g\nq~/Ob5ؿErvQg UCڬ\X!;[[8TY&T=6¶e,˳$C M|'p^I.Kdzxu} J_rw<7^_"p0]wü`9N%XAii+W$xAwݫknEپ+KVwλY3V#g*}¦`$R2CB)O)= _lJgʹү*|rGp7RW)Es#Iolѩe hol~qͩe=2?^LOt|6_xLFsnRr;0^SU6/;+Q~vd|%{fP\0V1f-&O0UL-\ *Z"%O'괼aVM~vvq_e"ue7tZײb~UUC=TYu\[ٸ:|e*-_YI_HECUO*I,)'i3oTC\/5\k*c5K?U|3g@8[T㝹 2݄i䭽ͬ]h㷧9rD%Rs輧Os>CS}idw~YUG:p斟_+ڒOZ6VTsG8)Tz$ krѭaRؼyL ;]=6˜<{tp`i>p EUQUPd8+X9pj UعIB?@VTNvػ9#g-LGd7V^_cMvi>=bIԗU6 d\_9QmѡaM *esėWc2h9*+T.u_ϳeNjtV`2hs~( = xckݜ|65 qu䵍ۑa7gUbm1%R |oغK*dвŚ6_r} ījZnskE8w$ vao(c#Ԙh-cZAvWyѰ+''}l|FȠ;^ꗡ |o3Tθ9tC4Y9ӑHAV@"Vmɇ aCeV\("l 4X.^F)j󣃭~Ȝ+*A3IO MNgzςv|H\,c]~^^,i9 ffƊQajDXw5Ԍz zh4j gW:k|77\s NV )kpuJ[ O?eo_s &vt9{f m.#V9kK[.:.| Kr'=ClQU8vǾN'v 2PUhRp`lv_~j+-?;}-sɴ¹[AuŦP6u8G2L`bԲnbˮ6ZR⎏iY!c'eĨVWFJu?;q\ u#rޫ/z&/8đ+^2ʞ55,je୵f= ?t>!W$vNlV+wQQŷcsjR&p76וu]ǛZE2]wB4m,'h3h%WT?<f3Nnb6x`3JE9e4֘x/> RQX f!ՙ߶hg7@(τ!\FCn6/v%b)͒RIDP,ͼ:3M5&e^bU㉠g#}O4O8[΍RWg⽳n2.%wM&̙d }Aުum nb):xJڢH$2L2O*\&}>ɠJ|mS#˷CܟLhaeVwز2'Q'iei22M2>׶hVơg̟*WgB[E=O!~(Vй8P\:b Z:< ;,Z^ZĠrDN O&$9e`/ 0İ7>'۟xl-Lnot<bp\A|4>1ΒV ΅ͤbQ4+Oͩ:zˮ57-AYe'E N#}s#XˋFv_3{Qlp\DUK=It: T^kaėdp"Ơ'NgMOnJm\\U1h$m-2pg1eu'E N@ ۣ1"1 s_k+gMЂ&+wsk8Ɓ. /u>FV#?|6 * f!9uG*%ص)AYu?ol)|IV̛rS0 _Za=`%~G_2-#(Ѥ̚Vd < ď{jL;a톼҄u/TY*w0V A&<ͨג̳fC_WnQ__|2J*Vxrv6>}3+S8ZiZ cAÎΧRza[ɓ'I'غ2MiYMʠH+1qnXRUbܗ|_nMxU 4¼\V3mӒ*zyu}y]>vrVlC,)s$u}(6YVI*6s??^XR9mM: YJx-˪ʾ%۟Ͱ2^׽0ײvxoĈ&e/B+/Y7qTE7'x@+P 2N3OOX[G_ūm|sWغ$<;QGr$pl(ǯqpϏ MN=xDJeY[MYQ9q55%_.of$2WOpTAEBQPη9pn]V+jh1sށI,꣡p55h˴3y83\e }euEzTxC{ \AUTfd*Үͤä0dUES^vm0V#'PRi?u z cܛ3I3H10Gf 3h$ʥV[i%&ciLZ2rvaֲu%ۦ~XӰcU Kl|xí(78i?GUD${ֺ:a\v}sv)2 X+^vvU" wFU Abw2%s^+xmaRo$. [VmG[{|'»GG\`'ːΨ,n.a@^ҖN?zj#dYmF})V~_ԈEA Qi5@9t͠;BGU1qgnaFӬocѹ[AIVh.ߩth5j^,Bj$V̳u'2;&P9pj;8 ̯1Kܕ†Ej|m ]?ʽ0CtsSYHnh2VWK!SeI]B$RL9`e'/?dʜF^SR_D8'.[$R !,vbIs*Th6sNp;sdP\f4/i$Ts rYWS29)XS S7|gն.b(N#xiyi~F⅁?Ta\P~-ֈ^Fn4}1^C]Ee7罁R_JE7Ll7┤l'I~8P : ̛/7kXT5#WYQgM ]wxHl#W}D[V>y8EË]]3rfzzI.蝱8XF,eMf> ̤H2Dv$"#ddIsW]Byl>N'xcKݴKʜC{|p~YV}'@G+2SVYH* i`EvgW2 uNEQMSt z 5%d|oi }Eu_ww5qIVDBvlF#êgzW;EU%~~l Y4d@9UF,:ltXg⪼]EmuflpcWXBG|x7@M# _zFV_oAs0%E&$ |sk];I{xl9r\8;VVW΁h|Z wv42Mӿ8zu=kVV_m9t+H_s soxom.I%$'K/͚+?ɝ?:Zg8gǗtF8Pb 2:'%=x#B.pfhBƦ}-Sc,o)͘(Ǯz`bJgA `Z2p?ą TeIUs_DN!/X\v P$Ɖ^"ʡͰTF WXderGYjI.|7F3;V8.8q7_n(ʏ?fZ6VΔqId. q?ļ:3kؑ/d \Y]t&U#W:" a,muyu٭})-Q??>oZ.; ~J0"#~Ty8, %o`i04osgR?NEU&x|J|x;!tA+r?L Xkm\,۠ bW]"VIV[ٹa\ci:G6u mt F$ҳ€;i]O@Mݪà`K4: *L*1@47N(ZkdA@FEV.b.\_ϮH*ʦNűQ~Yt (Wc$iYc2 3LFRDJYQ$)HuzQnƦc3=hti|168PA;']>,A5<;\&\yj$Cq ykpx9$#8 شX*q y۹I<)so,*ks]կk%O`#N!o7{Q> x^ZBeS*NzqJ*ikE_)LSN- ^o%jm ONaZ[3#ErCq+CZU9z""p rm(DʝgN: wcH&0md0 v)=+e Bш)L^'7<92i/vPH"p &I: F\kՊ*H% I8A$ BDAȓ yS!O"p INA<)'8ADV-,%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/images/s2shapeindexva--xwh5jadmcnm.png000066400000000000000000000754711524103652300223120ustar00rootroot00000000000000PNG  IHDR^'9 cHRMz&u0`:pQ<bKGDtIME YzIDATxg@SW7D Dqj`$@XLEn[{ D\6j(~O[mIMrhr{xso9P(((#(EQ:((֡DQE-'(uh9QEQCˉ(bZNEQr(XAm|MLEPᐎAtb5k>kUN Xf qRv؁.]ёt ```@:?ӧBu:U91/;4h\.~?(:3'(uh9QEQCˉ(bZNEQr(XEQ:((֡DQE-'(uh9QEQCˉ(bZNEQr(XEQ:((֡DQE-'(uh9QEQCˉ(bZNEQr(XEQ:((֡DQE-'(uh9QEQCˉ(bZNEQr(XEQ:((֡DQE-'(uh9QEQCˉ(bZNEQr(XEQ:((֡DQE-'(uh9QEQCˉ(bZNEQr(Xg\x8q"vJ:NS(زe nܸSSSL6 mڴ!K'edd 55pqq!I%$$ //zzzg}F:Z̑ٳg;w͛غu+H:ɓݻwqUl޼t$TXX8?oF||@ ׯ_Ο?SƯ3f3r9FW^oСC [[[ܺutDTPPwww 0"N=i?P(Ą 0gΜèQ'Nwj? w{;;;C(b̙شiZMP`ĉx1RRR`dd?6m >ltܙt\QPP>,\߃1uT8;;###5"UȉFULr 8;;;}M4AVVk̜9tT6{l8y;OM8_~%pMqub[O>pvv˗/IU9-'OT›7o;r.]@$!3 VL&M 33gΜYHGJ_~%R)RSSѰa>nܸqXh/ ???,Z蝏a o߾DZ_PZYNEEED6l?ށCtt4%*Rbb4mYYYٳIG*K.Ejj*b1cƌ   O?b}o118lق}j֕Ӌ/  agge˖97|ptt*YmTnn.-(%Ç͛y@ ?@zZbZxq߿VVSII 1h lܸVp8H$@ ӧOIG+ԥM6X,Fnn?>3jgϞ=DVV,,,jÇcϞ=pssw}Gz8Z6p8ؼy3>BQ:)R{v[[[<|4Z}ӧiA|rHRXZZy;nnnΝ;GzX)&Z)(挏VSYY`ee]vk{˖-CHH|>}(}vvvHHH@PPHW#0$fn)!ChMAil9UTT`000ÇѠj5ko6fffHOOGzz{麳g"(( ߿3d$''#$$N"=lV{֮]}p8DDDF+ J#ˉYL&!..NeĘ0a,X[[[\rYIhٲ%rrrVo9oHIIĉqqgBD"9 _P\.ǨQs:u jرcajj P |G_ Pg11rppd/_'iiiD(--Epp0闂5 >bzիh֬闢4*=z$/!===899!==D11p8u$WpqqAdd$ԾkkkH$BTUUaȑ_,u֩}LA dggk\AiL9) L<W\AFFUr舔 0KC bbJ ~@ ڵkG,GϞ=!! !1zh/ 1EEE xDzjp8Z BFBԩSqEdffb cccԩSOIDj?QQQĊann^]P?'&߇P(Ă D:zl`ʔ)#]QQaooדUV)>M)( /Ĺs琚ʚa޽:t͖g)::x11:z(VXA:Z'NIǩ֭[7#227o&GbcE11VZHQk,XN"өo69$ =pqTӧ1b+ƵD"m۪߹k7iÆ ʕ+Մbu9-Y)))0 @vv68*bb0ua\txD"0|qޫCǡC|rqTXr%\\\4X[N7nѣGsHHH@ppΖ?wD"T\\TiiipǎIL1ذ+W+ ]vA"iy -9 :111/&FV J[N+1 wXVt[vbmzH g}An݊HbiӆtZ߿͖bb0u!/(L___k^y_qi>}f͂B ^x''' 2D777޿U73$1'MCS/\L ?poW*r]>T:ְaC~È#PYYI:RYL6۬X*(唘ӧ#++K7Dcf%KW_S#XL deeaϞ=j]̙~ NR:fjjd>FFF6lHGK8;;w ]-[ Jt#>>| AҾ}{#>>5ϝ;*&F!Jelݺt ""b[&GqQh...xHx%лwoرCgl2 ><HAΞ= ooo=zj,0҈SL:WL 6oL8KB"hrػw/:vf1ܹS犉tR)(7|///>|j$ۘ#77s!bruu%Ŝۼy3mۦ?~aaā闃(. "/_T{|11.]QFÇjۯZ… DLL |ffffB~~>&N\h1`DDZ *33&MBjjM+m۶_~x]RRtޝ0j(|ҥKpqqݻ¿iڴ)233q%͖~:tT*EDDZ`ȑHNN+Vk 22jZRRWWWtv7.(ӵkHxxx|0I&Ÿqƍ҂ߘڴio߮;w8v @zجpi&Ny0ԭ[7ZL)(uSY9pttAh:SSSΝ;*-OS|7nTIA]p^^^طo^T˗/ȑ#onnnڵ+=Waaa UyAn޼ @UV!00Peᵉ 3)uٳgi1s 6(~' ** Τ1<(mL1uvmܹ7 ݻ X`FI#99FyyyyY :SXZZB*bÆ رcGw D"DDDݝ4NXX>s֭[SL;wTsŘ1cURPJnܻw<g"if| 0lذz-BZ~} yӶl2ƚ={6Ν >~)--.ݻwb9s樬y1B!&LI&E&8vU\h1)soعsg}xŧJAA|>BBBM*6\.탹9D"QsŤ|;vDVVV\Y*((~6acǎŢE`oo_~cSNhΜ9;vR ߙ'Oė6ly++/BIutD+Wb׮]"8;;#((iS1c`ƍ 駟oSTT-&%={R ^oذaXp!F+q\ٳ{\h1^׮] j߾}}˗/ @+--;-&={6ƍW*bnWlooe˖~M֭[u9ZLӵkW`ѢE,(qFqñgo3KKKZLj0k,7ޗĬ;h ˧&_ɓ'hf\%-&vl,Z2 7o&^ÇP夣Ԋ݋Cܹsp8VUULѴ䭂w4V(j +J*ˑ{6lNgSbR85Y!%Ѥ+gB^rIǫ~<( հ[gffb_x8湹AՇ%-&Bm؀Sh5znɝ(<慾j-t{yR K\Wu\A( +~/a(Ӄ&rE}PVJ_|AGEU㉉ h:CQھ9Ah;vl۠;y~" X /?@~_@Bީk.R|WHB쫸5Rɶ+7(W^ᾊơ*z_AB xoU-δոz~W+ 0zt($os#D!c$\VBVЫp!TtBi` ! 쌍E53 ORRߢlGNDlXOc71A~j51^ij&U(ko)Xb$.zL÷Mp[WtD\.ȑ#~:d *lũi'Vf͚S/_] Iq1:tsÏ~i1vZٷf/!CZܷVv쏸OAw GիI:IOOEkJ:N1b q `x`ɚ0m4Y#Ɖ'߰!zc;v $</^kdD:NZx1TyUF/_177D"n:үE SLEEE8~8w8y$BCCqiqLoY5)ݳ` 77o|W[UVؽ{ZnkMQW11>S?~~~~8s y!55[~c\.bccѺuk8;;h -J7) L>hѢEW ۵kW}кLQb:q{1x`|8<}9ZdzgHb B)S… Af͔]MfVl^|.(bzEu;ѱDضmk\f -gg%(&~ iiihܸҶ zcr􎟔ƫTL`TTT#77j˓'O₰0y;hԨlmm6mڨ},yL1ݹsiiih䥮>{HKKLLLᡶb:~x1zhhժ8ק())ԩSͰ0CNNڵk1P"gϞ!==J߇J~DӃ_,R&e/@aaaO5j???+} ?3v܉C `ѢEJ~XX6l[[[btYcG&! _хAuezqI=*{(JTUL PF!55wѣGQUUqΝ;DYYJ p nܸS"LS)AkHJJ¨Q JU+R >O=BVP\\"d2,T^^2<{ *aXh?dy~7ޤ 8G^^wGQuSEEUװaC|w۷/,,,Э[7M6qUUx1c`ƍprr¥KT 榍ƈ׫Z2d:___$''O>Qn)UL1b> \-ZN%;v,_+W4iѣGdr HJJ§5n9߯Uն@ ၔ_]ŜGWu1edd`Ĉ8z(|Zֿߵl`ʔ)*ٟ/LLL0tP8qT8)());{nMX- ػw/pyuމ)&==zc/)))5jVL׭[7#227oV~\]]o>xxx@"+U/^#tb\N }v_~Q)ڛtGǘ1cDH۶mêUT'''$&&"00YYYDL^QQc׮]j/&@9aðyfB\zDJd2 >\3g";;5v8t/_"118uaS5TXXPcǎ*$>R899A* |0rUZLwƲe [,,, H PZZ5k֨d?Fzz:QYY oooCœ'OPH>} BBB qitԉAi?4hÇoߎ#//oZj8::BP`ڵ*O~H9Щw(((@ ެrPTUUC*cǎ#QZJ]ŴvZ //۷Wv_>-ZS4nR)477ӧٳgcذ!(T*P(Dee%.^z;mDǏ___,Yt,('QRRPӧOU)dճUQLc|ϞxobHR& kWعmкKl YYYX2f JO¤>F%ݛzL|'ܹ3ЧOG޽{#Gb…TcE9i }yzIQY'II oQ#wu̚(QXLx Sp8ڵ+._-Zʕ+>]՜w&MŒ3Hy k fΜbBH$z߃b200Pٲ+O[UUAq1/ߖUTLPmY=n+W駟*_z;wSNŴiHV,YH$J/{QL߬ }NI\v wL g"qtTgOEEEXPkk4l&-[ŒSyflٲfƒp0h ۷oc̙*[-s/D(jC]{xjQ-[jưupoVmxp;.˗nNN4hn޼Y}Am[4¶_~AP4P-r9&O={ //+WĖ-[yf|JUsׯ_ fϞbXxXz5r9\\\FDi7jYҰukrF˜= kvvvć~Xm;wİaҥKѢE #99}>=zGGGb͚5v*u)--?JKKq43׮]P(Dxx8BBBHWW_}0dgg~HvvvH$ W\@ e_(}=iӦat-aϟH$Ž;D:N@OOhѢP^^N:"oS\\k񐐐`?~[v-mۆg⣏>>>C;wĴiP?#6mڤfeevĉUR~+v ///qjE# \.8&M #Q, bb 2ĠAp}F p\ 0{.>|c%exw"'' dffGb4ɸ}6ƍBA:b9 kkk4oF-L͚5C1h XXX꿚x`aa:$ۓSo[N`bb믘>}:8iC1BCCammO>sQ~0p@Biӆt,҉r7nPUU۷oCPлt"p88p͛ahh}̜9SkI6W(ߪU-{:T$]rrt:;|u1Slْt4љr%ƴر#\.p-xtzk޼J˩qW6xUYy{,>5xt:ر#5jb@ii)6mJ:ZD9) ߿1ƌC:cnpMXYY!##OL 1jÇQp e|L4oޜt:r HǨ3KKK 6 ? bڵ֗B)S/ ## 6$ }k5<ѣ]PӀqT! [B x @g J'0HOOr8vpiqtZxx8 [[۷>hٲ%rrr0qB/Dvv64-(Xt)BBBt.\tbC-( Ø1c`cc[nt/_D@Wтb9s`Μ9HyoԼyHQ+M6СCH$h JЂb'/nuUESPiiiZ[PZUN7oΝ;!JѺukq(%ƍʕ+?󴽠,[Cтb lذNNN|28:O J+i޽XbR):vH:8x |}}K:NGdd$ߓ,e˖4_Nǂ 8e-(|}}www|7<42уtJ hA+bccTJ:Ӷr:~8 dff> R#ZP쌄 ''tTBBFSFF&Md|GPЂb;;;;v AAA"GiKAi\9eeeaԨQHNNF~Hǡ666HNNFHHN:E:377.˗S'UN999 ±c0`q(xHi @jj*&NǏ:vFƔ_@$$$ƆtEEX߾}ɓ'8 BZP,ѳgOdggcؾ};8:O t% ** ...P{tyyyظq#lB:c *>>+V ?~'899apww' LA >^@Xǎ!JuVDDD!HpQ+_H$BDDN:B!OOO)JQk:t@^^|rTTTc,M)ݍ75k tJYP'Og}F:R]pQQQxZn%KĄtkݺ5$  'N?F֭tRsb>_hH#wB(bѢE&ruopUőTkZ=~g\xW\Abb"X:GP){aΜ97n8ц˗qm\t ^"r9k4imڴBqh7 *<s̞=tJ B۷O>ѣaddӧOٳ'1vXDEEAO1K.cȑx9[> QiVZ!'' Dɓ' Ժ[ ST]Pl?R(8q"n߾'N[nGVw"((WEE"8qFFFܹ3h1 SPfr***3|||`үC,otwR(|8qqDVZA"Ӌ/  aooK}(СCYWP SNťK qHNNFii)QQQA:z5L___4h'Nk7 jʕr^| ''' 47n$6pbkADFF5j544DBBd2XQP񁡡!⠯O:UKLA+(Sii)<<<ЫW/ l+y!''iiiYL C. 򗕕&&&4R[9 VVVصk8KQ–?>233!affV2ehh///~Z7͛7Ѡ񋁩z"YPj)'LoѬ=NNN%VP-BZZѬY:mC__h֬PVVpww9-&-CT2 011={h1QL.]SN!;;͛7׶\.ۇ-[S-URR777t UKGɛj*SMq000Ç)]P6l#G-Z(e\.{E֭%bҥ vM|j1:RO\.GHHG*M6!** RJ6ELL :w +=/ Э[7ܹPgA䧩 F³gJ#YP}ҷ;wB*u*ك^zA$˗JvQQ`mmMI0uA%W=z'OYb CeDFFB,M6*mЧOSLƎ;蕷:Hrb\_p 兢(UQvAEGGcӦMJT8lق.ptt-D,,, jJ߾Riܹx"߻ EieTLL VXDN:u #={Vmb ĢEHǥ4S:όei>}Z),$|'o'0uTdff⣏>"p H/ w|>BCC_IivA*@r^r*{Uߦ!k n[qiӠ[V۷!/-WCoy}7^߿Y3tr󇞁H5ЪJ!L8իiܹӃ^ &M09 SLiHǫ5LnhӼ9^KV7 F`wwXUB2@zn_TYX?DUI mG"&AUp*wj.~HǪ44ZUzB`Պd:9t Qvcp4k!!УqH`כNCKK sk\N׾Zo6,ÖǮxm«c_dX}J++IG/?AߌEC9e~C:V -u_ x O KIG0kky]g{:X?ɡq ͫo>Fϭq9] R_ѱJ,9;v_2چVk'/W (8 =u$֊^r0у MV+ezӃa~׀ӒohOh״)BCa woB,F\Mj=TVZ'CmG HUzj$1b99 LLA,U>5k:chLE3c[c&cҤI/#z@ޥ{!TIj*_\] Z7/!!'O8&7ouYE'ܿ<ᡡh]YVVSSZ_3fP( ł ٳgUG2L1l0 B7n"""BsE߾}s%F_h׮ B U<~Xq-b֭#Ǐ3&(>thݺҥK BŊEyyC㣐dc{)tXzBP(Ν_j:s H$@ @aa!jCyy9?[!##X|9ƍpppUuزe 騵vs4j֖t ӧ#33{~ p1d2t\13Ηzj888ffԟ>|8d2{o-["'''b Lj#KKKH$lݺ#S,wQ̘1l) ЂR!e֭[}B$vк)&.[6lVmk͛X`BBB:tD"W_}+WNԑ#G0sLdeeDgǣ(%s3?(++#iL___50ܼ+lYΝ; X`Ə_oÊ+Hb{b֬Yk7 ߟ)%JpcnCׯP)&:]eܥr߾}Xnѱܽ{<s j\f!ɣGbٲeDAGLL .\X\5 $(&@sCll,Zh///y4L& kuwؽ{7nJd,L1͞='N6MLLT>l2y1]=zUUUoU=1O hܸ1=[1РA"##W_u,̙3=o999HOOGXXZAGTT!HХKzm9ׇ7-:xT8R AUVV"00)eeepww):TbboR6mŽ;2Oɓ'+e-[ӧ!H0gbݻwcʕQ iAՑ PA9+IHH@YY UBi2xxxy8xҊ\~zܹSca~hǍS*ufffŬYT:=v܉իWC"(NLAЂ!ur?ӧQUUUjRxxxE8pҋaii,\wV>ڱcbܹ*GӦM'NfoQ*""k׮D"JGÆ /UL ۷ocܸq0Ծ}{{.]@"`Ŋ8pRcB3F 5mx"-(-i&lݺR:uR龘222,&@&&&HIIӧ|@Dtt4Tt999?>~|>jI&ŸvƏŎ̵ k.Q%_ƍU|bPN`jjd;w3gTجnnnر#VLnݺ!;;C\\\UPP>@̟?_hذ!RSSqM7X~= Hжz*r8x 6mJ /$ PS9B^^N_mbbt٘;w.9Rm0 )RRRp-1^|֮]={@*LA=P(T{1j,' 222IU).]`ĊѣGa̙8yd888 .$:$''tZv-bcc!HЦMY233ðat=z>#F5h9998|0V^RRRWWWtv"^L޽{#=='NDRRR-ZDz,$<{ AAA4ҥKYSL .L玠H@/N~kË/ н{wV?Fzz:Ə}laa!!d\ZVVFݣA,YxHRfԙj֬ TNk1km߾ j/^3>cܹ7nRRR"8::k׮% LF-©S qމ)͛k}AD" Tr /^co߾8qF)&{{{2rz-\)))F-HW\.bS1 sifhqBY_L> III=z4݋ 6ԩS ņ HG 典8l޼n"0|iD11,(OOO*(r\@,cɒ%uM !0dDDDhL11իWرcCtt4z聍7V+̤J###>|999Xb߿O:R(շUFIGZl5bXRN5gffb̙HLL$Ξ?@q8Ƽ;===hѢ ӧOqʒRBӧ#??b͚5#N\.bccZL >#ddd`ʔ)5M >דS/m۶}눯qƤ# yrtޝt,P(0m4={VfA :eee# `Y9w3~^5F x_LC~ uINNFnn.ZnC(Ύt,P(0uTɁHJ9<==5^Le'N;HD:ҿ*,,d%ֵe``^ˑ#G0k,ښtP(0e\t hԨHJѣ鉓'Oؘt ȉgԩS5jR)8A hM1ibȠDBɓqek]11\.݋VZJS `q9A呎ppp ֬YC:;wb…Jի8: 矵o[?ҤbX^N0dlll0b̟?)5j=z;5L&!pqJoOiK1\NYfΝ;J{0fFk baa!N8m|\.N8A?a޽TVPTLL:ӧO#SLyHPZZ SHd2B__>H`ǎ^PVLL>ǏǣG꽽waԩ6mQJJJ͛СC"!!-:p8ؾ}R J ВrYfBϞ=v޽ >iӦ/ =, ^( ^񁉉 ,(HTb`ٲepww@ k;wa{m܊v킞VjRaÆ8t-zb W^D(..6-+'Xr% PXXXݹs|>3gĔ)SHŸDۃ᫯Ҹk 泾-[#W%p8ꫯЫW/Ԫb b`4h\]]k }6x<f͚ɓ'O|".KPii)aiibR2z]#7Ihe9q8lݺyN={6&MD::??ѣi1TRR777t QQQp8l۶ |//w._ bΜ9X֭[WJΚ5tSΝ{nZL*Vҥb+'^~]+|>ϟ'Jv`z$A/_#vJ/BQ+(]+&\.7:vBDpa>o؁'O"<<#G$M礧#==rW^E޽cz15uTxyyk׮p8u('ς0a6n܈{ TRR۷oQ':JpML`k͕lSXXGVOhҤ V\IYfa?;vԹ:QN￿ ذau`b7P(4v,rt:{1^|Y?͛޽ BQ1uj C)'H|<}zzzر|駘>}:u7XT(Gy9mF:V?'Nv:T{[)0`ڶm[}Ժuk_Δ,Y'Om۶$Iu3\ɓhܩ?,eHG)\.ሏAqq1B!Э[7t Ñ bذa#ΔXZZ҅\YXs |>jְaCVݼys|wޤ͛cܸqcSD[˖-  ,,t$}}}8::")) ~)HD9`gg.ٳgSSS!>><t$JumR;v;Hi8v Iǡt-'ڷoDu!**tfooɓP:֣XYYY011APPH:kȐ!HOO+^z`ґ(-Gˉb]";;r'Igΐdo]GQFˉbݻ#-- NNN011H:>X,P(Dqq1A -'J#Drpuu%Iguyyyx%-ZD:ưƉ' DB:ND~~>1o}tfaadffbԩt=>Jh9QgРAHHHIiJ1qDTUUDi ZNFtִiSbܼy#F@ee%HDi,GGGϟ'G")) Ϟ=7IG4-'J9;;cǎpss/B:N311ARR4haÆt$Jr4lPW -Z@$t$JCrVZ'''o4.tx9HDi,]u8:"** #>}J:ah9QZ%44gÝ;wHipww-b1tB:rwuVZǏiӦP($Vf͚?3f̀>7oPؐ&M}}}!##z"b1NGǏEEE"N6m }}}gϐB:N;v,6n@@W=r5u45~055;N8D=rgΜB@&M`ll,<Ν4i۷N:@vv68 #'-2 ~~~@bb"affݻw#;;;w&?bСhѢߏ"4k \.t4/HLLrc044D||Xf royyyHOOh9頂6lg3jݻwakk1c`j7ZZӧqiL4Ic'SuGI0D"֮]m"!!AAAHJJR8n߾ S&233qet$Jh9Gؐ!Cĉ*akk3g/P(4i,<~ RZN:ݻAPPNiii8q":}\zX|9&Oʗb $''Æ ׯIGԀs|>Lt_}T*żyo>nŋXr%FqP¬Zbll zt$Jh9i7nӧOǴiԲϞ={";;-BLLRyy૯ˆ#2]qat ...x%H rbׯ_-[ݻwGnn.V\[k[?\]]c 6L؅"::}dzgHGTz*1zh":uD-[ ""NχۇC.pqq->|H:t"-tED"_DXZZB"^¢Ej\СCppp :}/_SSS|bk׎t$Jh9i _}kNo())e1bHb0bX#5F -'-?;wd)VZ!''P(:855cƌArr2>3)2e aggL|ᇤ#QJ@?sgΜag3KL< 9vBCCDcݺu t8r`- `P //>>>8x B!X YYYp&L* 9ӧC,6f Ď;၆.V&Ó .4B.ãG1ukTM8||6ӤIb{y۱#ߏC;R_s^]0#%]VƍX~=:ūWTPPu\Jhڲ\t}㮻TT GCVTT%G}d_?76ƍVHiRӦM|PȩXuZLBQ} B/_3XӤ F9xXBW&^q1룁*9<36\.'ZSÆ B:NSxQP 1jٓtZ)<>u /52GNNԧXu၀p^ĆAKrvF׏?&K]|ϡDh 6?NNr hbض-ڌNN0 Bc .&]vaժUAE׮h1i,zApE CC=FFF ʪy]4jDK۷cÆ ɁnݺE:UOD@@8!5(>֯_h%-'-pttDVV)Oikb޽H$h۶-8r2p8էhAQjڵD"A6mHǡB:J/FRRвeKq(夥pD * ,@zz:ѢE q(ņprrBFFzE:EՙB3pdggYf#Q*DI >δ(P(_H$hܸ1Hr(P(0e\|hԨHr>>>wޤ#Q3f nݺt4lؐt$JMh9~DQ%1zh<~066&R#ZN:...HMMEIGDHH q)D-' WWWZPd2C&㴘t-'5l0 )))(VdN8}}}ґ(B-3t+777|P:022B\\-&GIǹ"&&(bJKK憆 СC(ZNR]P}8)));:tCAiEˉ ZPڼxB;wFTT$O'& o%rEEEpvvF޽k.ZL[OHX :2EEEprr A}vp8ґ(DsuA}7PZɓ'6nHz'ZN;9;;c߾}E)MAAu֑C-'꽜hAQJc|x{{c͚5P,GˉWNNNؿ?ݑK:ݻcɒ%PB!:ZPTݽ{|>'N… Iǡ4-'FB!ӧOCi;wcʔ)1c8D՘#G O7n܀ OiӦCiZNTرcT*%bׯK.Ŕ)SHǡ4-'֘Eõk b Ci(ZNT"!!H$P,q%x<^!!!PUg666HHH@@@-( .\H$¶mL:h9QbccD҂a?#\\\W_ۛtJ rmȐ!HHH@`` rrrHǡٳDصkHǡ-'J) D!;;tJMΜ9aÆ "( @@:h9QJ7h ?~HMM%Rt9IIIxPZ ©S0zhC)Ijj*F'ObPZ2LA"99t$|gPZRDzz:ƍG Jcڴi'|B:h9Q*ׯ_?ЂPG3?tJGrԢ_~HMMŸq㐔D:UC1115kЫW/q(ҀtJwpuu:i墢ӧOk׮P:VoBСCIGa׮]Xz5$ :wL:tn߾Ǐ~~~r#餾}"-- ...xѥK :t|UUUxv D+++t֣Gpaȑ011!Itv(//GIR+('B}A.}7|}JJJsN={iڴ)F.] ϟ?ܹsQUUE:NR(g`ii KKK\~6l M3'Bɓ'ʕ+@Æ ׯ_#0zh1u˗/쌏>;wNGb5{{{󍃛Ə]v}8s aff~"#Q-NP/ŋ^]Lн{w`ɒ%ꫯHG/^zM𱔩)RRRcĈ#/bb?OKRٳk֬!S-/×_~hԨ?k׮GDDlB:+**c"99Fee%HZ/Dff&b15k׵rZ`233:4~KKKH$lݺck-LIC %%^BPP***HGZϯ{bbRAie9-]ft;v@xx8ZƍIǡjx5iA󑑑QWRPZWN7nđ#GUK/۷o<9r˖-#= ۃcPu```cǎ^^^(//'Ik,X=>PPZUNصk$ ,,,j| H$$&&1TPPD"]t ###xyyIJpB!;;NsmۆHbiӦ177GNN2220w\XL1h/.ѣGѼysxzzt$pBֹ\PZQN111ذaR),--뽽-[B*"77f͢Ǐu0"66ZH$«WHG8-BJJJo>,[ 999ԩҶkffL={&MUC=χ?/^L:\.111 IG/XKicAit9;vJUsiӦK0~xwlll CŞ={ЫW/D"|t$[x1N:lhB׶r:~8M,SeiҤ b1n޼c҂zwcɘ?>8p8l۶ }?N:k-YNBNNJMtIL0)))U?f9wӔ)S0}tq(5p8ؼy3 GGG<{t$Yt);LC[ J)++ &L@ZZ )) Ϟ=CPP-ܹs<ӦMôiHǡp83>}J:k,]G҆Ҩrƈ#}HNNׯo߾ 3g]PXr%aggGCڵkqQHRC Jc̙3 ±c'̖:=ƍٳ1ydq(X|9F C̺u#҈r:wqڒ=zFFF6l˗cҤIP,QF? G֯_H$VQXS tyxyy!66f[llClׯC `Ŋ5j8Ka̘1>8j~zٳRĂbu9]xH$"[ϖvVZq(3gƏܺut۰aÚ#Ӵbm9]|"v킛8̖ҥ D"Ζz*V^#FCi3g",, |>8*qFDEEA"kmOUӤbe9]~...8IOOѰ͖x"|>֭[`q( 3a̟?y&8JqF޽RДb]9ݸqk׮?85pe 0|>_kf_p...ꫯH:ƎEW\!Gi6mڤQЄbU9ݹsB/FPP8LFՊɈϟ oߎaÆCi1c`Æ ptt?L:NEDDT?NTtt4+ƚrw|>0vXq`ӦMpuu@ 'OHGعs'<==IǡD@@6m'''OYDDvDmےSgLAEEE߯^i`„ (Ŋ+raggV^>?ݱ{nCi???A  55j/;v@*jt11ڷoTZ=U',,t$,(ǏC(bرZҥKall A兘V_%Ii6___ IIIDW}Hl޼YkƂ"zZɓ'ppp@pp0+^ UФɈgΜ7h1Q*憘xxxo!?m޼:vH:1ŖS|ʩ>|Ɉ;8:ttJG 668{,8k.DFFjm11TPDŋ x:s+3gb޼y___tJ8;;c:t(R)8{nYDR{9|BC  cq8?.'QB@NN8vލիWC"SN  JD~)""" cǂYYYjdff"88 #P: H4OTTNEj;r*--t͛7ul7B(둑$''bXcȐ!8~8D,GTTV\ y#rQQQp8j$COOHKK}!44N§~J 4pssCUU'GGGbz#(L&6l={@O5R7|pA("99Y-s=RSS1f[B~!-- RYD"闁5HJ˩044D\\\i|||`ll 0m4lW)4|dee!''7&Bi039tJuСJJJp=ȑ#X`i1)Q!HTFAջ/^TH$4k֌ku}]WO4(m׾}Ϡr9,Y?z(f͚X>t|삪W9mذ8}47oNZ1R)/;wbڵtJj eeeXf;wQ̜9)\NӧaaaA5z̥LAVߦMuVE9rrr P(|||ƏװVÇCSj\NU94w'/C߯]ý{ U [gS5,+ //\ @OGszF"pnJtow 2 Z[~5^`ء5.;J^TowQ!yy( x%AB"D$,BI"D$,BI"D$,BI"D$,B/=Cbot:9Q$ EQ$ EQ$ EQ$ E*d1uVn6Qy(yǂFjaYL20֠$?Kgޅ^'7Dq5b5iх~_okO䋺j8D[q6E[EcСZ&*Dk\tsVԿ3l*a+ʶx Zx9꠷/B=zF<#WI22ĩ;P+}iȗڙEQљk gVe|Vϱf/Dya] l=JI+[Cf>Nq{`pnU(Hg(|:"3 Nުe)j5vCVĸ7őC]򶶞xO_YQ), l&=]l,õI:+%W^bd6;RQa/[B=ӷjуX,i>hϾzsRRGGi${3mE\󙲕^28e=_}@y-u~Ff=3Cn}RϔF'q9Tky=_+lu}Pϼebs!L)S  i>s߉`ԗߕAYeKcoKq<>7n\j>XZ\ⱗ v5iXa}Ӵ4h^ҫYFd|2K^lòŨ =vĹ7͑CnBփ>\:#Wa>V11уj7(0X_|3XY- >3?Dy,9(̞yXch,ݬo/9+zF[Ǐ|?MSIsX5f6x2"òdrF;}QnhP*b m|>|3|m%/SaR㋅V(VMy<xyKo%l`$Ň T(:-WUX`\;EkE6z*//WU-MvE^HEQFg|1DW9r?jUaw[XM:Xyks鼳ėy6,4|h34F\UqgK"(v[$,Ϩi8EWܸ;E{p]e_gsytAK3,be|de,/"u8΍zZZzg9TOme>SQ \i(dx*AG~; uNHXvgWM9^ GKy.qjɥ ^%!a[a% x:OiHר$,*0 ݛMsуcF&ZueyTIXT<6Jo$M{\l>0ߊT"a~3?h[ I2 Ek7<շt~HXVN{qnOs!:KIV2<VG} acfod:}Qky+@.0<`l.6gmk9 >9 ݥ[;l2cxPEES A氓 U8梫I$ t|k Frn#3)FRޙ,/(wx~R할-j篱 l!*vCrE9v:/7ŃA@jW'q| z:xD*Ǐ<Փ^yB$,`kXNǙcsٍ=bj1ݚ9`.:}Og>g.U lVFݩU\$,`-`iZ#..vס\pXFT+ R6;)_%e5ybb޾(~jW:!eL,q/FtG`Oչ\3177fi Y鮸tB¢7_Xۗ_4 ;Z+O&˻ӛeIXT)|0$MANFh9!`h,$Wzd_05IXThjߋ>+mf=-3-8y#;N@² 3 E塧͇^: \fL,]6uUݐ@j5 kip)] a'u6M隸馳Aery)>|obO]R :ZkIIa̕/D-"ځXMΝd0;VO; \=^EW\닲"fN=j]fFg3RI=gpbֈG*kN5$xI%}6.t3rg6n#ZG1!.;{BzcXzΝb5Uϳ ĹS i< O i2Kl]*4> .ȏ*z%KtrEaW~;Oy>SLUEQDb<.t1Ra6VMqNjYSZՅe|a޾ZnϖWZ7L-9ZfT]+@Մ%~,G=.٩“8zwsU Pad|04-a'.ٍ/[Ǣ)ti6UA+@Ex? Ĩuhˆd9`1ʻwc8:xuTemEe6VX:q;^sbb!onQoqwEn9[Qayv~)w8ZYK*",ٜ'IdWgcQ>z24q;cw7Q(R}ٗz6ǧ牥28^+ ~b,&V^L3]AQ!-a+]GZX(WņEָ Q$ EQ$ EQ$ EQQ"D$,BI"D$,BI"D$,BI"D$,BI"DQ՘%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/images/s2shapeindexva--zvfp9yhjq3.png000066400000000000000000000636541524103652300221220ustar00rootroot00000000000000PNG  IHDR~LQ5 cHRMz&u0`:pQ<bKGDtIME YfIDATxy\e9;I',l TP]AGG((3sudfDQT !$dOIQ@N/zS}n4M!b! $"KH ! HB!B $"+H ! HB!B`;^Vj+( D$huB =g>6MEE0@e/d]Uǂ(#\ #Mgg{cs 1p8:ז2.`:=aV$UUs觢yC0鈣 Fz $ǿ[VGJSl_Hd/}~rB4uYyۘ[]bi*E(j$:8ًCus^٥VҺ#zWiVauIBI`ˌQ2w,e:_`IU85%e=ӄ'79΢*B#8'\eWX,č0FY]NNxv[?{;"x]Kg`d!0 gR:+vM|MxeMeys .! nY]$119چi/꒲oDQ9=KBO)DꎵN RldVrz]qЇi’T\bdMF_U9 DRmB Cq(=zljodW{KeYs5vk$ҩbSl,raSUϭ-{7ƚIkh+^&N+3[3{(^#!)[v"!J5,^ju9Y; &,^AUꒄyo%(G"{@QKpp_!63i52BQ?au@5 tfWP⨱HZ.&CPb\#!)[vi3E۱=GWaWdrd~8E^#!*R[xi#T_3uYV^`0.ymGE1 Sf85@_6²+.'+m;b 6Uaż5ش}B!('>o`nJyj!^?]S`5B䟬XC>|R斬KtFya 4WQ)ܥBՁ2Gvp~l&]@o4aIS%nKB Ձt0d!UF˙tHML+A !XR0@ˬ.gE:yh`z V$*+0u*&UZ7yt]/p2 f[]BL zJ4Y]Τ2Mxrc/qJv̮FBuM;ظ=}Q. `FBUv&&mAsE5oZkph*vުB!Dʪ@ꎵJ RldNr˙TyKf*HQX&F#=,XdMi+5D ! O| m#mh/`u9&InRɼR* B*&`D.K~O&ML]1ymӄ+)FBq%УtDpA5(9R݃ ~'Fʩ.+Bq& 񊍃m8j~&\(ї{HM30nO !hL?N уVļV_K ~R7δ*ʬ.I!ҤRLq0%eWaS{0L{eNk$!ZHB6L5SeO7gck$1i47~daV_ێAvq,onFBq:)imC#_[X{|^5.5B3@ꌶ1p60ݿkPmqҏyy 7BՄRˆهy~$yo0c/wcFE^KB1ىN+)WX}&y)ӋFB1>a:1=(I_9%Z}&6xxmfjkeBָIw#Q P8| 65?'3{zJR[dތ*duB޸D{x~늩+9>zb{m,jFS%\R\ۏn=S1yi ;:/ z[Scjvꒄ"gK %8]Ք$ZծCa^)mq{~AB6. t0O=RLLK(3J0/sWfi%M !XK me`'b೗[}/ *i*mQ9>h*"-;"{֧ J/Uvyu0in躉i*=ӊ$bSbDS4UC!3ъU{GK; }qB1nM3dTp:'Ӄu.Nryird AS !xA>{)5kdzso iV&hV!̈́+wcSwJQ)NPmuB7&44Ng&&&{Qfi96[GA*&4sۭ.Q!Ƅ?Q㙎h N$FInZ]ǡb)m bn+f?RmjtL 7Z}X OcW+E7L6FHB1~&w:Ob`x;ԐRɮCV#ycfA꽳Pm=&+AUa'dɮtM0u7[}cR챳pn-$!N3EQ9B"dus6MaG0T@(eRɩtMA7Q߭p09ԕ[م"MNQЫ$?&-)="$!I$ـn7ۣ$ƒ>tu.G!r%sPWI}Ê(iWYH.KeU߃1lTiΠ!Dβ H ߇1Y1M@wH,eu9B, $YGLp`hخũtf1mݲN!΅x碠wxi#i{1&)vEe$ei m~J5$-ù?J`v1 ;e$e> ޹ڈnbb\vܾ!lVL5riWY62J: bT,$Of+2zwϾ`VNGfBL$bG%I#J[u]ebZ{B$)fc=Yx*z"c2JB5wQd s(ۣ$]a$!8YH 9 0 38U{C݉B!&CVR>ġ]a\ٗ$gUovst"|n .JUeDRDX]Θl*]FIBq:YHiu9cxz~Fw Pn$)+Y^pj^MSVKBS@hd^QҢ~J6(I!N*kYVL89@gd匉*3cr"+em {3sI.ez 1BՁTc+"+zrDU.Wv% !ěeu )({f+)N'$!8AV@c0Iw匉ˊ;!8^񣤝.gMQ3J=!YH85/zc.gLV/d.I!(% lu9cࣲN0{PFIB9HUi85}Cۭ.gLVs(~b\L )B(iwKࣺp4IWrr9Hծi8T7=6G.g.W A% ! ^Ny\ou9c6CMH!r*]U]]V3f`0IQr.TE3݁%ͬPW$O9 $!Dʹ@v:c(cu9cv#C2JB $MѨugvs_Ҍ7S*\ GRt(IQr2j=ӱ)v#{ &z.gVϜ-($!DA@;#sI{6X]Θ5VyZb8&0!t9Hh#݄V3f,(`[kCFIB’Ӂ)vj11QRC*``"$(9Hu8A(g ] numnkY~=0sL-ZIJehnn>k+ͬs ʌz $!D~ʫ@v74btF[410F.wH$غu+ 6m}QYd +V`ɒ%x</ nݖi:rbBU L6Sj a0pz9+)s{dŊX}s8p͛7yfZZZxx477|rVZEee%TSQ8I4qZ6 !ĸ˻@pk~?^C/;%'(455> [laͼl߾۷0e/_ŋY`6yfyN?c"e wb?~Į83%%%\q\q$Ivƍٰa裏Yp!˖-cʕ~koV{tDZSb[+.IQT]۩u;-ZĢEg>áC۳g֭cݺuʜ9sXl+V`ʔ)~-.x1s 0,&8_x?Z}YBqN " 3J tE[&w|;#49p[ne۳dU=Uz mϫ\b!9)@:Ko.紎ogtM71x0c]V.`o/æHv2WRUYb2EZ}yBQX<4/Q}p*Ϟ[Ķ">0ML]wzߛdEm5oz46ͣi׾f;fWIԙ=os[Fѵ3BRP ݱD+έ@:FQPl6f;@o Juc*aױH&[{#uP Gק~Miy-aVb?e ! DR 3Z]Θ4{y7t1/yrf5/#܅ QpXkҬ://o0;4]DE\w0{^̮8ܺ-gˆQ5)p9E 49Mo ^ju9cR[%'Ӹn*uSt͍CC*{of޲e4/\Ό PUI 2j=@fU dZlcMqig$D*@(WN m8[ FY`B.|~Uְ9ѶJ=o K;#!XAR^ƬV3&>R=$C%9Nlgd~st>pB;{^W4%ߎu^zIќ )rvFwoeWy*?(Ա_ x%IS;F;%G; F<޾?WČep_+;҄'WЁ  /~ǭ.iLKyl)4W=~҅gX ( x/aӨQюOKC!7jHݝ=oZ,?9]w+Vs2þ= xs;p?rŌnӏ20@CѠ݈[29H}vŕ~V\P~lٲIS^7̑ Vy=zArlL #%_1iL~u!rYARh8LMm5GYyu'+.mLNueN: Jsxd+>=fl|l;RS< 3EwYmS :v?x^V_^aӶ4_ہv Q sdw8kgd޶7Q54kELa"xǬ4>oǵ#m$.m̚3sG}եEQ:}kn :7mTUo{oJ xzO(S#x3 \| FkNK3jVWjmWb_GNmV)DΑ@:U\I:bu)bVm涝zu:D[ i 4:>(+8HǹKpaUn6`nX]N^XLH";>Bvʥ_] buB$ .lf{艵Z]Θij7iY]N3CWY }:uUlya'D匙ǩQW$6VS {'xMsgJ*욛0tS~ I +{s-=.e\:znP6ɞ-+/|6cYW@eMm-xm V_9C$\s3RѮ AG:t?uKnʌyMӿ" ِ@:/ڿLHX]ΘU)SVRٹuU~ڨi"[pg/K tn+=۬.g\4tmߧGybTVss~\n4m}U>op&q'pl~>"+I _m繿aˡP"6窳u,b>۰?OB7 zgu)bH׆΁ wF4b%wP #UUC(< b!Ɠ*g#MN׆;^mw(2u44Uo#E"tsPXKn&ǨbV]fW vo]R$ksƏioYC V^=8зrڑ@ ׆m_.tw s>0tK"+H ˯tJC?ap>W꒎Y~NCOa^~>?1VHgʑ)?6( LɌcOE7UN( ׿TU/O% a9 `,6?D匋c]Fo<ݏj|S/KW^auI'0!#?!,'t.r%]CyK3k< tk_|lv>|XBK:5^1^YK˞mV#$kv)NA013M~g}[4/\nuYgx 1t,$҂V΋yL[]θ8n`(o#^z \n/]4]duYgm+1{{ 2HgIU4V^=qo匋YC:zswaa<ybڌV5*pnAU5 Z]@ˮtJ??fu)gog(&HZ]Ψz_ٲyť|+ߡqei\x;H%<Ϭ.GKH _AE] }mV2nvmV׆T2xm=UneU}2v=;^!&(*;XYaM#HHDٿ5*Kyee7~' TZ Q*rTkqPPL`WF,&nv ?Q\ZauYfK9g!ݼY]JiJtZ.e\( ̨` ep Q?u&|Y]ָ{?f?>L_O~%ِ@bG =džңHG"Y IwGM &Deu=t:œ1i$Fɮ:؋I1ӫݨ*EƳ]`W<̌cuYw~*®m.GI!tJl7ium׎ή}f 嶺 gw8yǍd"o 1$AH uGZ]ʘyrSWM҆I`(;:-sym YxE|sa;~&͂2wxO[]Nm;vFn/k}O2M%҄']*q˜;pNh8O|Uլ~&u4v}G.G e\( ~GD}vj=3. N=_JގkRt CarhhAkߏc!(Wġi 'X\˻>p+-&Xye-_{7<|Kw[]F8$艵l `ޤs A@-߱k . ]ep5NGߝv #7SW07>Ɖ3%ѰT65(h| {_Lzeә,9+"9-C . KCSTNvۑYtΨˮ???qW[k"H AEQ艷aiGfSi(wggt$z{$U= 9< uBI±_gb)x6NNaeaY0xm `֌%d} qHc)v|2BNʝ V F}4Juo઩o?Syu:J zQ(n M=5 .MUwٍٱ.z_CH QPjXY0Mg<].OP aD"KJΟgzs]uEġ)]prXF]ο@W01-?QYʟO Q1v"bOd 1*vTMw Jd÷m.똉u%#)8xM͆˩i8&7F]EP`bAƱI7zoI02} uSwb^͸lvb,$g/8w48T%e%0w{9^/wy'g϶s6p"ש\ؽ ~QY4D28/1격&vvLfa%:9P& 1RP(vV3o7vK:tep]whuYlG]m@pT'׉$RN${ kvᲫx]($IF7LY8\V KI {%vHoH$w˖-[{겲e?f;y ͆:фN֜YpthL𺩋쒻gP3$~zuf\[ob2H ^Mss{vQn=/smϲe7᰺O|ϳ>ˎ;N5nZchI 1$= ;>Gcu}k.o`|U~?GOg܍ˮ1嶝 Q t5Pnky[ǰvmF(b͚5|+_Ad/֬YÜ9s8|0O=)(0ʍi`(fuBH Api^V׼esY퇹LCSyu]b1}Nd EQ[PU_W z?\cUf7l!$E0ǡvTVUVduIjӦMyqnFnV ,Ě5kb8#u a= QJQZBbbj*\uҋ/w]Rǹ曭.IG>yٶmISSS|!Ɨ(d:3l$i/afbKT/o|ӟ=Eя~,pHN8#ޠ# kI Bk5"!],*r&G/|뮻Y+?><'}L 嶝Y?ށKݨyhx<?QU䪫$q.p4z޷{ Ȩn N[0ʅMS F1dH1=-,x?9r_bҥyx<R]]Yn6MIڀai#$&WARL'L1h%S|.iBo~~-[m݆᰺,a!g?Y~Fi2 m$+@21i~5Z]҄jiik_\r%|n[]K.eٲez!fGX](0H]=xmEz {]BY|+hZwg[otO vuiHuK i0IGd?ªz믿wA,xP _qn*++1 j'ܶ)eU.(g%M͛7swǹ[$)tM׳{n_  bT {63dS}zڵ|;!J}oDlr-EO8ﴺ2Q( &LL,bp7K0/uO}S}ﳺ$#/^իo3D:[)++ߝ~i/|믿D'?uDk004 "G芶`S쬮沺 EQUW]euI"UTTkoH0vtD@8 wP䬴 #__l6կrq­har Kpvx\nq& t&yH}vc..~o^-b6;ouY( >r38TY& WR85i37M?>~;Od54IRǎu?E*^ˁ32vڐUB\NRHghi2j=MV4naҥ|8A)]*VZ[[ٻ}d}^>;Y}ϸaWlxv7ir"M894q ˖-_(B!8p쯽{[Bk:`Ʊj6; Lce%J[oæ:lv<]D D@:pjb{%*gÁַE(⢋.+_ &l,崶o8t:6ʪpT54Q=e6eUSJI ӎiEBX('/~XՙĠa|&sUWܹ]vq@Zˁo1رﾛX,Ƶ^˭ޚua馛$G969>tZ!?@32UOv奥]v6.,""T _4 ]N{%W^y{ｗd2ɍ77luI'xȶmxG'Cmtz|Nqy-eUSXt{2i6R_f>mEB䛜?"e+.i\]Cu~꒎iii _[lٳgs%q COxz*Sxͱ[keUSkugB;%g55Qoq'?IwY]Yr/~uqadB[imO4zN]C#>'ngYD ȉ@7vbu h駟GQ>sW[]CCC| _੧"---r-h:jwQV=򚩔4RY3߇mq"!@ %i @AaUJ.i}Q~_*W\aIw"_˟H-N?pյ}LwiG:!.)mc(ً^N0փ+r5Z]=#}ĎӪŞbRoDž{:9RB!$k `0 ˙Yt_/m~h(bN1. Es`p;Oʡpq][nݙFzJx+"dM ͚׬*vHs7%HO<>vu|ο&|-P111*3aT1`B/&BRFrg=n?)h{'4ig  u3cy|otd(9+k&̙85\Z(]SPU3/5j5{2>opN|B们!ܮ;jסY> {:DPU=)߿M84Ģ .}2zEB!N%+)$G)uT㵗Nisi,YA0vv#m  de_0B`&iĦAdE yN뾸#ӴuQSYQ?&kynE?yBT`ہ~z`"Yˊ@wP=i3B{b"Y?T*ɥknl%΋[ 57p0xs.1gX!0"+(rO뾴3d/o0oHt|*K*m2Z]bΰ|tt1d'oK̷n0 w\wY~ !cW0Ӥ SOap/~fIݠg0BU47)ə?2 w 4>cOgEW[f !U:miRitZ'&ɤN"mL' IXJ'ᔉ ;[R,"J)vTNk~(B A~kYx7?AQn?tV]BHA:u҆A*N$:N2 xR?ݩ7'vxUNې) 49Q8qo8ұuY̠&veVi(;c̣_i6>dUVUB́@IzjdĒL&I 4HXp"93TSPlx6\Mr(\^nTPշNv'bHԖ@gw5eG MrW[ԕ)/vq~y`w8-_go*D>K H #eHI$Ӥtd JLDGy&*x]pq5n[&H ]lx*:>˱gԸh^ k_`(sac:+N~ӱ,zhz9MGi ̬?[4yXܓ8.>hȪH&~,`>rk,։u҆N*HRƨneE;".ˡw\t(8.^99u^v$ j˜̨v3M^vǺXѝD]H, d-fؼwh`JR-7 +/ǿm͘܍BLoœ:T&XR4aKI$ RN2izಫx r6|pqmݹ9(Y9_v]w/p?__p9XHG{'~wvGx~K7+VRV⵺cI %T]?᯷aox`Z")~sť|~oǼ9\2s0:d]I&z:2dH咱Lhcgi ׯ7ȺCӊyUƒ@HsP_±40MsGdO߽*>)CP__Ys1gޢIAInJ$R)̲aJ$S&9L;5K&ٻxANCCD: fTH?QS&;ú=AҺ"<7&(ѝ:z>)._?cʴ+߉_tsIT*2NL$ T*Mj$\}R_)^nG_`wH\U5o8達2S8T7ZC[C*4z,~m§t7E2t.wOunZf PY]Kye- w~sHutC'7uR4ɴI\&8hp+xz1n`ys >wa@Htb~?z rd.5<~65/܁wyX2M_?~  oIStu0;n䱇~?-!b|:{C} ^5 IcT';@(Ca6)5%E_OM [f7K0~>B @&dA!b ()Jii9z|-bB*ﻤ?o`0wv)Ugw$N@JIR'ծ }_`0wJ1NF` u3cy|o,D&Ip8B`p C     v!&":} 8fNG^ꡣ?B4b̚@4C~TFg>isi^D#!~yF'۩Hi 2I:ɄA$&>fʧ {^}.3bQR@yE5UR\RJYY eTWPS]FZ.[VN^}QZZ:'bT8K]t_7iHtc: ޹hĽۑ9z/x\˻>pkNm>;NN"B7!b)aDisht3w_c˫I .8"/ tx̪,aMZ qK t`$E{_>JMe[ Һi̴IF&d:QL . !Ɵærc {yeO/ g2xO&% Sg(كJg=On2gtz5yܯ;ӆ6HLC˸>{_'Y OQ):~ K=ma4M>яFO<K$3iCIx&xG;r٩/3{4~Dc)5UYI aԳel-Mo5"!:D\h*Ӹ2HMѷq;U<m*naRp3vKd"k<|LI5 4$zPQcoEUhCTN#<9s*nPQ8Uv ӆ۩ۡvfF!RYout &x=4ѝ>&<^t3E:14yW~peS֘[2!ʄр8Ԝ_1&(<>]VSs$7tey `BY ->&;#m4?;y%8~9v߄ +#! n7aS,ɹ0 cT%bRt% *qNX]͹@lsޥBL &gd@:'#!,]q9s Hfغ :_FH1=LTk+Ye !DA' 4^ۑ{@wP/#!4QEQ`dhob{ !xC"_8RBMV}9뭾.!(1 $uN!&W`漣_1q:HaeH!&M "4(ٱizFT`5 !DsvS &=Bn%c$|^ $=L5[}=BQP:G|s{72Nv jj z.*]S!(aLiwۭ.gFHnQE܌`bRa!5~I fTJUQB1:91!%8}UV_BΑ߹|H] 3rBS84|Htn ) x.GvF;u΁6V_BΑvA%1ct3Mg&v%!G;4Vrj9s #b]PRGq.m鎶Qi% !DL(P͟;TH=Vfjw#v5Y!P0&0{mxt%GofX!t#Xs Ӡ3vZU.kd4i݌FH=񃤌8i85+cePo5'xQCGx ^Y]'0LzI4,=#$EUfd !DJMJFH<$ܚڅtˁߣ\0@]P:!J 9[aV)P^3!%:GGHY&SCewRG {՗)' 8U} !M]T@oW(hCպ2רL6E"?¼|jvy?Y}BQp<Өl籶Mc((ovho"~/?Ii#1B!M(V1as͆B ?mbB4 $!YAI!DV@B$Bd $!YAI!DV@B$BdYT|%tEXtdate:create2025-07-09T15:55:43+00:00r5%tEXtdate:modify2025-07-09T15:46:28+00:00 (tEXtdate:timestamp2025-07-09T16:08:22+00:00 IENDB`doc/design/index_validation.md000066400000000000000000001126351524103652300167500ustar00rootroot00000000000000

S2ShapeIndex Validation

Better living through invariants 		Provide the ability to validate shapes in an S2ShapeIndex according to one of several correctness models.
Author: Sean McAllister
Contributors:
[removed for privacy]		 Status: Final
Created: Mar 21, 2022
Modified: Jun 22, 2022		 Self Link: [removed]
Context: [removed]
Visibility: Public
## Goals Build functionality to validate the geometry in `S2ShapeIndex` instances with a configurable model of correctness, with an ultimate goal of providing functionality to replace `S2Polygon` IsValid, and implement an `ST_IsValid` predicate. ## Motivation `S2Polygon` provides an `IsValid()` function that checks a number of invariants that are expected to hold. `STGeography` is valid *by construction*, and `S2Shape` doesn't have a validation function at all. We don't have the ability to take an arbitrary S2ShapeIndex and verify it meets the constraints to be treated as a particular geometric object. We'd like to be able to take an `S2ShapeIndex` containing arbitrary geometry (points, lines, and polygons) and validate it as a single unit with a configurable model of correctness. The goal isn't necessarily to validate the consistency of an index itself, but rather to validate the geometry *in* the index to verify that it can be used in situations where e.g. an `S2Polygon` or an `STGeography` are needed. ## Background ### Why Validation The purpose of validating geometry is to ensure that it meets some set of constraints that let us reason about it and make statements such as "point X is contained in polygon Y" robustly. It's beneficial to think of geometry topologically, as sets of points that divide the domain they occupy. We can define multiple partitioning schemes (such as points in the interior, exterior, and boundary). But the simplest mental model is to view geometry as point sets partitioning space into two pieces: points that are part of the geometry and points that aren't. In the most lax sense, valid geometry is just geometry where points are unambiguously members of at most one of these two sets. This immediately forbids polygons with self intersecting edges:

Not least because determining actual points of intersection is numerically difficult, but because we have to make up an arbitrary rule to determine whether the overlapping regions are part of the interior of the geometry or not. Note, however, that polygons with multiple disconnected interiors are allowed under this definition, since there's no ambiguity:

For S2, it's always possible to rebuild geometry with e.g. `S2Builder` to remove any degeneracies and ambiguities such as duplicate edges, reverse duplicate edges, or polygons with overlapping interiors, but this can often be cost prohibitive, especially if it's known that the geometry was originally valid. We would like to be able to simply check that it remains valid according to a specific model of correctness and continue using it. Validation lets us verify our assumptions and operate on geometry with confidence. ### OGC Data Model The Open Geospatial Consortium (OGC) defines a standardized hierarchy of geometric types including points, line strings, polygons, and more specific subtypes. It also defines a set of "Collection" types which aggregate geometry together. The type hierarchy can be seen in the image below, which shows the types and their dimensions.

A 0, 1, or 2-dimensional `S2Shape` would correspond to a `MultiPoint`, `MultiLineString`,` `or`MultiPolygon`, respectively, and an `S2ShapeIndex` containing many shapes could be any of the above, or a generic `GeometryCollection` containing a mix of dimensionality. Note that the OGC types specifically require linear interpolation between points, which means that edges are "straight lines" in the chosen spatial reference system. Using straight lines as edges has shortcomings when working with geographic data, which is referenced to the surface of an ellipsoid. To address this, the `Geography` type was designed, specifically representing edges as geodesics. #### Validity There are some geometric configurations that are simply not allowed by the OGC spec. Beyond the basics of requiring points and vertices to be non-infinite and non-nan, there are restrictions on some types we must check for `ST_IsValid` to be true. `Points` and `LineStrings` are inherently valid (though not necessarily simple as we'll see). Polygons, however, have several restrictions to make them topologically reasonable: - May not have any cuts or spikes as they affect closed-ness. - Chains must be closed. - Chains may not cross and chains may touch but only at a vertex. - Polygon interiors cannot be split (i.e. they are one connected point set) - Chains can't contain each other (i.e. they must face each other properly). - Said another way the winding number of any point must be 0 or 1. Cuts and spikes in a polygon are forbidden because they can make the geometry an open set (i.e. not equal to its own closure):

Split polygon interiors are also forbidden, and interiors can be divided in non-obvious ways that have to be detected, such as a single edge crossing the interior:

Or, being split by a chain of connected holes:

#### Simplicity The OGC Simple Features specification (SFS) differentiates between geometry that is merely *valid* and geometry that is _simple. _Simple geometry is always valid but the converse isn't true. A simple example of this is a `MultiPoint` containing the same point twice. This doesn't qualify as *simple*, but it is *valid*. *Simple* geometry is constructed in such a way that it's possible to unambiguously categorize every point as being in the *interior*, on the *boundary*, or in the *exterior* of a feature. These three categories of points are used to define relationships between different features using the dimensionally extended nine intersection model (DE-9IM). For the built-in OGC types, the rules to ensure simplicity are summarized here: - `Point` - Points are always *simple*. - `MultiPoint` - MultiPoints are *simple* if no two points are equal. - `LineString` - LineStrings are *simple* if they don't pass through the same point twice, excluding the endpoints for a closed LineString. - `MultiLineString` - MultiLineStrings are *simple* if all their elements are simple and intersections between any two members occur on the boundary (endpoints, closed LineStrings may not touch) - `Polygon` - A *valid* Polygon is *simple*. - `MultiPolygon` - MultiPolygons are _simple _if all members are *simple*, no two members have intersecting interiors, and any two members that touch do so at a finite number of points (i.e. not along an edge). Ultimately, we'll want to be able to determine whether geometry is *simple*, *valid*, both or neither. ### STLib #### Validity The OGC spec allows `GeometryCollection` subclasses to place additional constraints on the overlap between elements, but PostGIS elects not to for `Geography`, instead treating it simply as a regular `GeometryCollection` with an appropriate spatial reference system id ([SRID](https://en.wikipedia.org/wiki/Spatial_reference_system)) set. [Simple](https://github.com/libgeos/geos/blob/f2784527e9b397817ccdcba207bc17b21ea0c976/include/geos/operation/valid/IsSimpleOp.h#L52-L94) and [valid](https://github.com/libgeos/geos/blob/2b1173ffb6631762cc438dee5ebc67b65b83ad78/src/operation/valid/IsValidOp.cpp#L250-L259) checks are applied independently to each member element, and elements are allowed to overlap. This presents issues when we wish to process the geometry robustly. ##### Higher Kinded Regions We can classify a particular pointset by the [winding number](https://en.wikipedia.org/wiki/Winding_number) of its points. Points that are in the exterior of all geometry have a winding number of 0, and those that are contained once by a polygon have a winding number of 1. Additional nested containment increments the winding number each time.

The DE-9IM models relationships between regions of winding number 0 and 1, and the boundary between them, for a total of three region types. It's possible to extend this model to accommodate regions with higher winding, but the number of relationships to track grows extremely quickly. The DE-9IM has 9 total terms and thus 29 = 512 relationships. A model supporting winding 2 regions and additional boundaries would have a total of 6 types of region, for 36 total terms, or 236 = 68,719,476,736 relationships. Modeling winding 3 regions as well puts the number of relationships over 1030. The vast majority of these relationships do not have a meaningful name in human language and so aren't terribly useful when trying to do "real work" with geometric data. Even the DE-9IM only names ~10 of its 512 relationships. In the interest of tractability, it behooves us to limit ourselves to regions of winding 0 and 1. To avoid needing rules for higher-winding regions, STLib adopts a rule intended to disallow them altogether. Geometry in a particular `Geography` may not overlap in such a way as to have redundant information. Representing multiple overlapping layers requires separate `Geography` instances for each layer. ##### Dissolving To enforce this, STLib operates on *dissolved* geometry, which is a canonicalization process that removes ambiguities and redundancy in the data. It's implemented as a cross-dimensional *union* operation that merges geometry and only leaves geometric features that add information by extending the covered point set in some way. For example, when two polygons share an edge, the extra edge adds no additional information and raises questions about the closed-ness of the polygon, so it's removed:

Sharing a single point on the boundary, however, does not affect the closedness of the interior, so it's left unmodified:

When a higher dimensional object overlaps a lower dimension object, the overlapping region doesn't add any additional information, so it's removed, with the lower dimensional object being split as needed:

#### Simplicity These rules are intended to prevent overlapping geometry, so that a given `Geography` instance partitions the world into two sets: contained and not contained. In general, this means that elements of a `Geography` must be *simple*, and we also disallow features that don't extend the covered point set in some way. Additional constraints that STLib requires: - Reverse duplicate edges aren't allowed either since polylines can't overlap the boundary of a polygon and polygons can only touch at a point already. Duplicate edges are always forbidden. - Points may not overlap any other points or vertices. Eventually, we will allow polylines that self intersect as in a GPS track, in which case we will have to have a separate check for self intersecting polylines to verify simplicity. ### S2Polygon Validity [S2Polygon::IsValid()](https://github.com/google/s2geometry/blob/master/src/s2/s2polygon.cc#L225-L232) does the following checks: - Vertices must be unit length. - A loop must be empty, full, or have 3+ vertices. - A loop can't have duplicate adjacent vertices. - A loop can't have antipodal adjacent vertices. - Loops can't share edges (no duplicate or reverse–duplicate edges). - A polygon can't have loops with zero vertices. - A polygon can have the full loop iff it's the only loop. To ensure the polygon is suitable for point containment queries: - A Polygon can't have crossing loops. - And no loop can have crossing edges. ### S2BooleanOperation Validity As opposed to S2Polygon and OGC Geography, the requirements for geometry to be valid for use with [S2BooleanOperation](https://github.com/google/s2geometry/blob/master/src/s2/s2boolean_operation.h) are comparatively lax: #### Required - Polygon interiors must be disjoint from all other geometry. - Duplicate polygon edges aren't allowed (even among separate polygons) #### Allowed - S2ShapeIndex _may _contain any number of points, polylines and polygons - Point polylines composed of a degenerate edge AA - Point loops composed of a single degenerate edge AA - Sibling edge pairs such as {AB, BA} - These may represent shells or holes. - Or may represent separate polygons touching. - Points and polyline edges are treated as a multiset and may have duplicates - Polylines may have duplicate edges and self intersect. ### Interior Tracking and Edges We'll discuss briefly how interior tracking in indexes work and why this imposes constraints on the type of edges we can have (i.e. duplicates and reverse duplicates). Each shape in an index contains a flag indicating whether the center of a particular cell is contained in the shape. Put another way, we create a mapping of S2CellId => [ClippedShapes] when building an index, and each clipped shape knows whether the center point of the cell is in the interior or exterior of the shape. This enables queries such as `S2ContainsPointQuery` to draw a line between the query point and the cell center, and merely count edge crossings to determine whether the point is inside or outside of the shape. Conceptually, tracking each shape's interior is done by drawing a continuous curve between cells as we build the index. We define an *entry* and _exit _vertex for every cell based on its *ij* coordinates and move from the entry point to the child cells, to the cell exit point. The entry and exit points are chosen so that the *exit* vertex of one cell is the *entry* point of the next cell in the hilbert order. This ultimately gives us a curve that continuously moves between the cell centers:

As we move the curve through a cell, we track which edges we cross and toggle the containment flag for the corresponding shape. The net result is that no matter how a polygon is distributed amongst cells in an index, we always have an accurate accounting of its interior. *But*, this requires that every edge we encounter moves us from the interior to the exterior or exterior to interior. This 1:1 requirement between edge crossings and interior transitions is what gives way to the rule that we may not have duplicate edges and that polygons must not self intersect. To visualize this second case, just imagine the interior/exterior arrangement of any two crossing edges from the same polygon. Interiors are on the left, so the opposite side of each edge must be the exterior. No matter how we arrange it, we can't make crossing edges consistent with the 1:1 rule:

Similarly, duplicate edges require us to toggle twice, so we remain in the interior or exterior, but since interiors are on the left, we can't have interior or exterior on both sides of a double edge, because one side will always be oriented incorrectly. *Reverse* duplicate edges, however, present no such contradiction and are allowed.

What's more, even between polygons, duplicate edges represent a double containment issue, because we have two interiors on the left, and polygon interiors must be disjoint, so duplicate edges are prohibited everywhere. As far as actually detecting crossing edges, interior crossings are comparatively simple. We can check each edge pair in a cell and see if there's an interior crossing point with `S2EdgeCrosser`. But how do we detect whether there's a crossing at a vertex? Such as this situation:

The answer is that we can number the incoming edges as -1 and outgoing edges as +1, and visit them in a counter-clockwise order. We scan forward from an outgoing edge to its subsequent incoming edge and if any chains have summed to a value other than zero at that point, then we know we've got an edge intervening and thus it must be a crossing from one interior to another:

Note that, to support reverse-duplicate edges, we must be consistent in how we order edges with their siblings. We take the convention that outgoing edges in a sibling pair must come first in CCW order. This means that if we start at an outgoing edge, we'll always encounter its reverse duplicate on the next edge and stop scanning, with no other edges able to intervene. ## Design ### Predicates
Predicate Description
ContinuousEdges edge[i].v1 == edge[i+1].v0
MinimumChainLength 0D shape chains must have exactly one degenerate edge (a point), 1D and 2D chains must have at least one edge.
NoAntipodalEdges No edges with antipodal vertices
NoChainCrossings Polygon chains do not cross, they may meet at a point.
NoDegenerateChains 2D shape chains must have at least 3 edges
NoDegenerateEdges 1D and 2D shapes may not have degenerate edges
NoDuplicateChainVertices Chains may not contain the same point twice, excluding the endpoints when closed.
NoDuplicateEdges No duplicate edges at all.
NoDuplicatePoints Any points contained in a 0D S2Shape must not overlap any other point or vertex and must be represented only once.
NoDuplicatePolygonEdges No duplicate edges {AB, AB} between or within polygons.
NoReverseDuplicateEdges No reverse duplicate edges at all (e.g. {AB, BA})
NoSelfIntersection Polylines may not self-intersect, excluding endpoints.MultiPolylines may only intersect at endpoints.
NoSplitInteriors The interiors of polygons are topologically connected (ie no pinch points)
NothingContained No geometry is contained in the interior of any other.
OnlyPolylineEdgesCross Only polyline edges may cross, and only to self-intersect.
PolygonClosed If a 2D shape chain has more than one edge, it must have at least 3 edges and be closed.
PolygonFullOk A polygon may have an empty chain if it's the only chain
PolygonsTouchAtPoint Polygons may not share edges, duplicate or reverse duplicate. They may touch at a point.
Single2DShape Only one shape is in the index, and it is 2D
ValidCoordinates Points/Vertices aren't inf or NaN and have unit magnitude
ValidDimensions S2Shapes have valid dimension value
We can distill these requirements into a list of predicates that we need to show are true for a given set of geometry. Different subsets of predicates will be used for different validation semantics. We define five semantic models to cover the background cases discussed above: `S2Valid`, `S2LegacyValid`, `OGCValid`, `STLibValid`, and `OGCSimple`. `S2Valid` is the most lax semantic model and does basic checking that interiors are properly oriented, geometry doesn't overlap, etc. Degeneracies are explicitly supported. Altogether these are the requirements needed to be able to use `S2BooleanOperation` on the geometry. `S2LegacyValid`is intended to support `S2Polygon` validation semantics, and is a combination of `S2Valid`, `Single2DShape` and other predicates. Finally, we differentiate between geometry that is merely valid according to the OGC specification with `OGCValid`, we add additional constraints to check for dissolved geometry for `STLibValid` and, lastly, we check for polyline self intersection for `OGCSimple`. These rules are shown in the following dependency graph showing how predicates roll up into final semantic categories:

### Index Confidence Given a pointer to an `S2ShapeIndex`, how do we know that it contains consistent information? It's possible that a user could give us an implementation that's inaccurate in every way about the underlying geometry (inconsistent interior state, etc). It's possible to bootstrap confidence in an index, but it requires repeating the interior tracking logic that would have been used to build it and verifying that it's consistent. This is somewhat expensive and, in general, we don't expect to be dealing with adversarial indices. So we'll take the position for purposes of *geometry* validation that indexes were constructed properly (e.g. via MutableS2ShapeIndex or similar), so that the relationship between edges and cell centers is *consistent* and edges are in their proper cells. ### Interiors On The Left As long as we don't have any duplicate edges, we can *assume* that the interior state of the index is correct and check edge orientation independently on a cell-by cell basis. If the interior state *isn't* correct, then we'll return an error that edges aren't properly oriented. We have to be a bit careful, however, since we can have multiple edges of a single shape in a cell, and they are not, in general, oriented the same with respect to the cell center. We can use `S2EdgeCrosser` to count the number of crossings with other edges from the same polygon between one edge vertex and the cell center. The containment state of the cell ***xor*** each crossing will tell us the orientation the edge should have. We can see below that edges that should be oriented CCW with respect to the cell center will have an even number of crossings and those that should be CW have an odd number of crossings.

We know that every time we cross an edge, we toggle the interior, and that interiors are on the left. So, every time we cross an edge of the same polygon, the orientation of edges relative to the cell center must flip to maintain consistency. We also assume that edges and cell centers are consistent, *but* it's possible that they can be consistent, but in the wrong direction. The interior tracking for a polygon is either entirely correct or entirely wrong. But, since we assume consistency, we only have to check a shape's chains once the first time we encounter it to convince ourselves that all the interior flags for that chain are correct. #### Initial Seeding So, we can draw an imaginary line from a vertex to the cell center, toggling as we go, but what do we use for the initial interior state at the vertex? Since the vertex is part of the shape boundary is it contained or not? And we may have multiple edges incident on the vertex. To resolve this we can note one property that's very useful: The interior of a polygon is always on the left of an edge. That means if we start at an edge and rotate an infinitesimal amount counter-clockwise around its first vertex, we'll always be in the interior of the shape, from the edge's perspective. If we keep rotating, any further edges must toggle the interior or they're improperly oriented (see above). Given that, we can take all the edges incident on the vertex we want to test, sort them counter-clockwise, and toggle the interior bit on each one we hit until we hit a synthetic target edge we draw from the vertex to the cell center. This gives us the correct starting state and we can proceed to cross edges and toggle the interior normally. ### Connected Interiors It's possible to have edges that split interiors without any interior vertices:

There's no containment check that will notice that the diagonal edge is in the interior of the polygon, nor will edge-crossing tests save us. Fortunately, there's no way to add an edge in this manner that won't make the interior state inconsistent, and thus either the edges in the top half or the bottom half will not be oriented properly. In general, split interiors are allowed as long as it's not due to an aberrant edge like above, or caused by self-intersection, S2BooleanOperation is fully capable of handling multiple interior areas. OGC semantics, however, explicitly require that polygon interiors be connected. And, in general, interiors can be split in arbitrarily complex ways by chaining holes together, including cases where the holes are disjoint from the shell:

We thus need a robust way of detecting chains that touch and working backwards to determine whether they split the interior or not. We can reframe the problem in graph language by considering each point in shape where more than two edges meet (a _tangent point) _to represent a node, and each path of edges along a chain between tangents to be an edge in the graph. If we do this, the three shapes above look like the following graphs:

Note that we do *not* completely connect tangent points on a given chain back to the start, as that would always complete a cycle in the graph along a chain, and isn't necessary to capture the connectivity of the chains. If we removed the outer three holes in each arm from the second example, the graph would become properly acyclic since the centermost hole does not form a cycle:

If we consider any shape where the chains never touch, we can see immediately that it will be a null graph containing no nodes or edges, and thus trivially non-cyclic. In the case of a polygon with one interior ring that touches at *one* tangent point. The graph would contain one node and no edges, again trivially non-cyclic:

If we allow the hole to touch the other side and split the interior, we have two nodes and two edges (one along the shell and one along the hole), a cyclic graph:

To split the interior of a polygon, we need to form two interior regions that can't be continuously reached from each other. A useful analogy for deciding whether two regions are connected is "Can I put a pen down and draw from one region into the other without crossing the polygon boundary?". If the answer is yes, then the regions are connected, otherwise they're not. The only way an interior can become split is by forming a closed loop around an interior region, either by connecting at least two points on the shell by a chain of holes, or by drawing a connected chain of holes in the interior that separates a region. Either way, there are points on the polygon boundary (interior or exterior) that you can start at, and, moving along the boundary of the polygon, return to your starting point. Polygons with disconnected interiors have *cycles*. But, is the converse true? If a graph has cycles does it represent a shape with a split interior? The answer, in general, is no. Without even resorting to the fact that S2 works on a closed 2D surface, we can find a polygon with a cyclic graph that doesn't have a split interior, which is simply the complement of the third polygon example above:

This looks exactly like the graph for the complement polygon above. We'd like to exclude these valid polygons from our test, but how can we tell them apart? Let's further consider how chains might meet at a point. Since we're already going to check for crossing edges, and properly oriented interiors, there's only two ways that two chains can meet at a tangent point: the interior can be between edges of the same chain, or between edges of different chains. We can call these two situations a *bounce* or a *pinch*, respectively:

We can see in the first example how each incoming chain "bounces" off the intersection point, and doesn't rely on the other chain to define the interior; if we pulled the chains apart horizontally we'd have two disjoint chains each containing the interior. In the second example, however, each incoming edge in each chain relies on an outgoing edge from the *other* chain to define the interior. If we pulled *these* chains apart horizontally, the interior would stretch with them:

We can see how the "pinch" configuration in some sense separates the interior in a continuous topological way. A bounce is equivalent to two shells touching at a tangent point, while a pinch is equivalent to two holes touching, *or* a hole touching a shell.

We can easily detect pinches by looking at each ingoing edge at a vertex, and seeing if the next edge (ordered CW around the vertex) is the next edge in the same chain or not. This makes intuitive sense because we're effectively saying that, for a bounce, there can't be any intervening edges between the ingoing and outgoing edges of a particular chain. If we restrict ourselves to building a graph with nodes just for pinch points, then we can detect split interiors by detecting cycles in the graph. There are a few special cases we have to think about though. The first is a shell that's pinched through a self tangency:

This is still equivalent to a pinch, and splits the interior. It's somewhat special in that the two chains that are pinching are one and the same, but, we can treat it the same as a pinch between any two chains, we'll just add the same pinch point *twice* for the same chain. This will ensure a cycle in the resulting graph, which we'll detect. In the case of a hole that's self tangent, the pinch becomes a bounce, and we'll safely ignore it:

Next, there's no reason that a tangency has to be between only two chains, for example, here's a bounce and pinch configuration between four chains, we can even have a combination of bounces and pinches:

If we look at a shape containing a pinch like that, and its associated graph:

We can see why we were careful to define the graph in terms of the tangent points, with edges connecting them. The central point shared by the holes on its own doesn't generate a cycle. If we disconnected the holes from the shell, the graph would collapse to a single node, which is trivially acyclic. We can gather the information we need for the graph as we work through the index. If we store a mapping of `S2Shape => [(chain, vertex)]` pairs for each shape that has tangency points, then at the end of the validation process we can use a [disjoint set](https://en.wikipedia.org/wiki/Disjoint-set_data_structure) data structure to find cycles as follows: ```python def CheckInteriorConnected(tangent_list): tangent_list = sort(tangent_list by chain) # exact ordering within chain is irrelevant ds = DisjointSet() # Create singleton sets for each point for value in tangent_list: ds.Make(value.vertex) # Add edges, if we find two vertices connected, we have a loop for ii < len(tangent_list)-1: curr = tangent_list[ii] next = tangent_list[ii+1] if (curr.chain == next.chain): curr_root = ds.Find(curr.vertex) next_root = ds.Find(next.vertex) if (curr_root == next_root): return Error("Disconnected interior found") ds.Union(curr_root, next_root) return true ``` Note that we expect most shapes to have zero tangent points so in the common case we do no work (O(0)!). In the more general case, the disjoint-set has ~O(1) complexity for `Find`and `Union` (technically O(Ackermann-1(n)) which is < 5 for all realistic values), so processing the edges is O(n) and thus the overhead is dominated by the `sort` call which is O(n log n) in the number of tangent points. ### Validation Process Details With those tools available, we're now ready to define the validation processing. We can break the process up into two stages. First, we can run any checks that can be done independently on the shapes in the index. These include: - `ValidDimensions` - `MinimumChainLength` - `PolygonClosed` - `Single2DShape` - `PolygonFullOk` These are easy O(1) checks that don't require index information to verify. Checking them first will at minimum tell us that polygons in the index represent some closed (possibly degenerate) loop, and they provide easy criterion for short-circuiting the rest of the validation. Now, we can begin the validation process in earnest. As we go we'll maintain two additional pieces of state: a map from `S2Shape` to the CellId where we first encountered it, and map from `S2Shape` to a list of (chain,vertex) pairs for separated interior tracking. We'll proceed cell-by-cell in the index, validating as we go. We'll assume that the index is valid until proven otherwise. The following pseudocode shows the basic logic: ```python # Initial O(1) checks. MaybeCheck(Single2DShape(index)) for shape in index: Check(ValidDimensions(shape)) if (shape.dimension() == 2): Check(MinimumChainLength(shape)) Check(PolygonClosed(shape)) MaybeCheck(PolygonFullOk(shape)) # Store tangency points tangent_map = Map() for cell in index: # Check dimension 2 edges in the cell for duplicates. By definition duplicate # edges will appear in the same cell(s). Check(NoDuplicatePolygonEdges(cell)) MaybeCheck(NoReverseDuplicateEdges(cell)) # If a chain touches itself, both edges will end in the same cell at some point, so # we can detect duplicate edges locally by just checking the edges in each cell. MaybeCheck(NoDuplicateChainVertices(cell)) # Maybe we shouldn't have duplicate edges at all (e.g. for OGCValid) MaybeCheck(NoDuplicateEdges(cell)) # Maybe check any points in the cell to ensure they don't overlap any other # point or vertex. MaybeCheck(NoDuplicatePoints(cell)) # Check basic validity for edges (doesn't affect duplicate check). for edge in cell: Check(ValidCoordinates(edge)) MaybeCheck(NotAntipodal(edge)) MaybeCheck(NotDegenerate(edge)) # Check that polygons don't have crossing edges. Check(OnlyPolylineEdgesCross(cell)) MaybeCheck(NoChainCrossings(cell)) # Disallow degenerate chains for STLib MaybeCheck(NoDegenerateChains(cell)) # Find any pinch points and add edges for shape in cell: tangent_map[shape].append(TangentPoints(shape, cell)) for edge in cell: # Check that edges are continuous. if (edge.shape.dimension == 1 or 2): Check(edge.v1 == next(edge).v0) # Count crossings and check that edges are oriented to keep the interior on the left. if (edge.shape.dimension == 2): Check(EdgeOrientedProperly(edge)) # Since there's no crossing edges, we know each edge is either entirely inside, # entirely outside, or a vertex of each polygon, so we can verify NothingContained by # checking the first vertex of each edge against each polygon. for shape in cell: if not shape in first_cells: first_cells[shape] = cell if (edge.shape != shape): Check(!inside(shape)) # Check for disjoint interiors. for shape, tangent_list in tangent_map: CheckInteriorConnected(tangent_list) # Index is now valid. ``` doc/examples/000077500000000000000000000000001524103652300134425ustar00rootroot00000000000000doc/examples/CMakeLists.txt000066400000000000000000000002671524103652300162070ustar00rootroot00000000000000add_executable(point_index point_index.cc) target_link_libraries(point_index LINK_PUBLIC s2) add_executable(term_index term_index.cc) target_link_libraries(term_index LINK_PUBLIC s2) doc/examples/point_index.cc000066400000000000000000000032201524103652300162660ustar00rootroot00000000000000// Copyright 2017 Google Inc. All Rights Reserved. // Author: ericv@google.com (Eric Veach) // // This example shows how to build and query an in-memory index of points // using S2PointIndex. #include #include #include #include #include "absl/flags/flag.h" #include "absl/strings/str_format.h" #include "s2/s1angle.h" #include "s2/s2closest_point_query.h" #include "s2/s2earth.h" #include "s2/s2point_index.h" #include "s2/s2random.h" ABSL_FLAG(int32_t, num_index_points, 10000, "Number of points to index"); ABSL_FLAG(int32_t, num_queries, 10000, "Number of queries"); ABSL_FLAG(double, query_radius_km, 100, "Query radius in kilometers"); int main(int argc, char **argv) { std::mt19937_64 bitgen; // Build an index containing random points anywhere on the Earth. S2PointIndex index; for (int i = 0; i < absl::GetFlag(FLAGS_num_index_points); ++i) { index.Add(s2random::Point(bitgen), i); } // Create a query to search within the given radius of a target point. S2ClosestPointQuery query(&index); query.mutable_options()->set_max_distance(S1Angle::Radians( S2Earth::KmToRadians(absl::GetFlag(FLAGS_query_radius_km)))); // Repeatedly choose a random target point, and count how many index points // are within the given radius of that point. int64_t num_found = 0; for (int i = 0; i < absl::GetFlag(FLAGS_num_queries); ++i) { S2ClosestPointQuery::PointTarget target(s2random::Point(bitgen)); num_found += query.FindClosestPoints(&target).size(); } absl::PrintF("Found %d points in %d queries\n", num_found, absl::GetFlag(FLAGS_num_queries)); return 0; } doc/examples/term_index.cc000066400000000000000000000102101524103652300161010ustar00rootroot00000000000000// Copyright 2017 Google Inc. All Rights Reserved. // Author: ericv@google.com (Eric Veach) // // This example shows how to add spatial data to an information retrieval // system. Such systems work by converting documents into a collection of // "index terms" (e.g., representing words or phrases), and then building an // "inverted index" that maps each term to a list of documents (and document // positions) where that term occurs. // // This example shows how to convert spatial data into index terms, which can // then be indexed along with the other document information. #include #include #include #include #include #include "absl/container/btree_set.h" #include "absl/container/flat_hash_map.h" #include "absl/flags/flag.h" #include "absl/strings/str_format.h" #include "s2/s1angle.h" #include "s2/s2cap.h" #include "s2/s2earth.h" #include "s2/s2point.h" #include "s2/s2random.h" #include "s2/s2region_term_indexer.h" ABSL_FLAG(int32_t, num_documents, 10000, "Number of documents"); ABSL_FLAG(int32_t, num_queries, 10000, "Number of queries"); ABSL_FLAG(double, query_radius_km, 100, "Query radius in kilometers"); // A prefix added to spatial terms to distinguish them from other index terms // (e.g. representing words or phrases). static const char kPrefix[] = "s2:"; int main(int argc, char** argv) { std::mt19937_64 bitgen; // Create a set of "documents" to be indexed. Each document consists of a // single point. (You can easily substitute any S2Region type here, or even // index a mixture of region types using std::unique_ptr. Other // region types include polygons, polylines, rectangles, discs, buffered // geometry, etc.) std::vector documents; documents.reserve(absl::GetFlag(FLAGS_num_documents)); for (int docid = 0; docid < absl::GetFlag(FLAGS_num_documents); ++docid) { documents.push_back(s2random::Point(bitgen)); } // We use a hash map as our inverted index. The key is an index term, and // the value is the set of "document ids" where this index term is present. absl::flat_hash_map> index; // Create an indexer suitable for an index that contains points only. // (You may also want to adjust min_level() or max_level() if you plan // on querying very large or very small regions.) S2RegionTermIndexer::Options options; options.set_index_contains_points_only(true); S2RegionTermIndexer indexer(options); // Add the documents to the index. for (int docid = 0; docid < documents.size(); ++docid) { S2Point index_region = documents[docid]; for (const auto& term : indexer.GetIndexTerms(index_region, kPrefix)) { index[term].push_back(docid); } } // Convert the query radius to an angle representation. S1Angle radius = S1Angle::Radians( S2Earth::KmToRadians(absl::GetFlag(FLAGS_query_radius_km))); // Count the number of documents (points) found in all queries. int64_t num_found = 0; for (int i = 0; i < absl::GetFlag(FLAGS_num_queries); ++i) { // Choose a random center for query. S2Cap query_region(s2random::Point(bitgen), radius); // Convert the query region to a set of terms, and compute the union of // the document ids associated with those terms. (An actual information // retrieval system would do something more sophisticated.) absl::btree_set candidates; for (const auto& term : indexer.GetQueryTerms(query_region, kPrefix)) { candidates.insert(index[term].begin(), index[term].end()); } // "candidates" now contains all documents that intersect the query // region, along with some documents that nearly intersect it. We can // prune the results by retrieving the original "document" and checking // the distance more precisely. std::vector result; for (int docid : candidates) { if (!query_region.Contains(documents[docid])) continue; result.push_back(docid); } // Now do something with the results (in this example we just count them). num_found += result.size(); } absl::PrintF("Found %d points in %d queries\n", num_found, absl::GetFlag(FLAGS_num_queries)); return 0; } doc/examples/term_index.py000066400000000000000000000075301524103652300161570ustar00rootroot00000000000000"""Example of spatial indexing with S2RegionTermIndexer. Information retrieval systems work by converting documents into a collection of "index terms" (e.g., representing words or phrases), and then building an "inverted index" that maps each term to a list of documents (and document positions) where that term occurs. This example demonstrates converting spatial data (points) into S2 index terms using S2RegionTermIndexer, building an inverted index, and querying it for all points within a given radius. It is a port of the C++ term_index.cc example. """ import argparse from collections import defaultdict import pywraps2 as s2 def main(): parser = argparse.ArgumentParser( description=( "This example shows how to convert spatial data into index terms, " "which can then be indexed along with the other document " "information." ) ) parser.add_argument( "--num_documents", type=int, default=10000, help="Number of documents" ) parser.add_argument( "--num_queries", type=int, default=10000, help="Number of queries" ) parser.add_argument( "--query_radius_km", type=float, default=100, help="Query radius in kilometers", ) args = parser.parse_args() # A prefix added to spatial terms to distinguish them from other index terms # (e.g. representing words or phrases). PREFIX = "s2:" # Create a set of "documents" to be indexed. Each document consists of a # single point. (You can easily substitute any S2Region type here, or even # index a mixture of region types using S2Region. Other # region types include polygons, polylines, rectangles, discs, buffered # geometry, etc.) documents = [] for i in range(args.num_documents): documents.append(s2.S2Testing.RandomPoint()) # We use a dict as our inverted index. The key is an index term, and # the value is the set of "document ids" where this index term is present. index = defaultdict(set) # Create an indexer suitable for an index that contains points only. # (You may also want to adjust min_level() or max_level() if you plan # on querying very large or very small regions.) indexer = s2.S2RegionTermIndexer() indexer.set_index_contains_points_only(True) # Add the documents to the index. for docid, index_region in enumerate(documents): for term in indexer.GetIndexTerms(index_region, PREFIX): index[term].add(docid) # Convert the query radius to an angle representation. radius = s2.S1Angle.Radians(s2.S2Earth.KmToRadians(args.query_radius_km)) # Count the number of documents (points) found in all queries. num_found = 0 for i in range(args.num_queries): # Choose a random center for query. query_region = s2.S2Cap(s2.S2Testing.RandomPoint(), radius) # Convert the query region to a set of terms, and compute the union of # the document ids associated with those terms. (An actual information # retrieval system would do something more sophisticated.) candidates = set() for term in indexer.GetQueryTerms(query_region, PREFIX): candidates |= index[term] # "candidates" now contains all documents that intersect the query # region, along with some documents that nearly intersect it. We can # prune the results by retrieving the original "document" and checking # the distance more precisely. result = [] for docid in candidates: if query_region.Contains(documents[docid]): result.append(docid) # Now do something with the results (in this example we just count # them). num_found += len(result) print("Found %d points in %d queries" % (num_found, args.num_queries)) if __name__ == "__main__": main() doc/pdf/000077500000000000000000000000001524103652300123755ustar00rootroot00000000000000doc/pdf/dd-index-validation.pdf000066400000000000000000033607301524103652300167300ustar00rootroot00000000000000%PDF-1.4 % 1 0 obj <> endobj 3 0 obj <> endobj 12 0 obj <> endobj 18 0 obj <> endobj 19 0 obj <> endobj 22 0 obj <> stream x}JԂ(28hiRpi"VSAOHStspu+.c(#ARx@?F[V[G@`*dK$O.K o@6`O,f'˘O asx0A6vf 8{c7%opZ:u Q 0Q٣F *Ԑ(SDGACAajgrx]s PxM cvhO> stream xkPpv=zPz1M^։K&ЋW΍1yPƒ!ZO浗їIؖHMڬSS{eE!N-JHn%r0)OXX7%zHʠ.ISI< @έ}X0|{/(mHNA/$wag;D0 @~;N`N^\'&lkD 2 oK3b$0Lv3v*͠๘ǜ>MHѷkOV5̺d ~Iyzv;`N;+vwT!N6rR |CHﴫ XtMVkT CVa6k|*Gz7q}/}'GMȁ ^4>vx7&@wߒ+d b6=˩o%"AHWo5EX{\Ys Xqedyrc(EN?Iůho2EʊPG8Q֞WRa9;xIN9Aj ^MX9 ]Jn Gx=V73xi;75(#CNiYd(H +幒F: eE]4;) #wz4Ց endstream endobj 21 0 obj <> stream xc` x_`dQy2BX$*Yj0y0  dȫpa>Hy78!L!ztj]磋30HhŃ@?HܛD#1K@60abMi"Ⱥ0v}tr;$C|F %fG~ w0QJ?W A endstream endobj 23 0 obj <> stream x]o7߿Js8vl6^s)pؕ6#Cr83i˹OegV=}lh zot^};aMַ}>6?S݇w>u}}ۿ)޼{N((2>~k~l~OoM4=;߸z_>]__<}_E]??m7}=vFo7h|4/3&]|_?8|H׋s[Od;>q>`ut*Fp>zHQbTňΩp K7IEйYD'pOTB4bf >a0 Q>lG ͋(YHB@;$d8G@f:oooƔվ2}kǁVG{qD)އe:ByuZ瑵xkZ=F*靃dУ]ۂ1>qK[޻7NKDIf18딢Z& .b6>sz3uB ͅ]C]9 *~ò1בD.IK0k{togu%XnciJf6 +$]NQ*(}e]eֺ=(I^NYmZ+%]4znE*E+IL"VA9=# !jnZ8O}t{9l \~dZrTrnbP:qq+.1^}lR*$0hnՉRqОIgN6&ot[ Z:~5kK_u**Ӑbm{jR熵O5͠k3/D191+t˧j6C=ܵ_o YxZ['d#^< dpf"tM%+du6}ڶ&뼡m]~# mo[NaCfX7Hm۞: ύӔ(/m1xj-C_ߏOi.GNsF4/]eezgOJ{Y* j!_U_Wv.uΥzsȔ^VZaPHS_PH*\b&)gЎ /ZUw4rf 2<1@ҀB"?ڝ1ؖ%fA@>Q:wLs elOB7FfIHs1rm֯{Dı3v]ʒfy q]ɬYs mH!>< .w 8犧)! =qPg#Afd(X=ꁰ O>Le.\9Z `Cs"+zI}!  e 58 5<`@pQYf;u.*œ>iWīK/]y )c;=E=nCe4t/x;!N1ҝt+VFXԝ %V_ pՖ,cU4#&՝& J_t'z`S v@+a-Cg&`hR lhR9A ΀?F:F먛;E&.*'At6Bf4\ h~%VDn[$k# NЕG|%r.RV Z(2'G]]9 D9D>s\ ͚Ȧ4UZtLILzSW5U+7xS,bG5wf6lb- $ap(CbE) gQlJot&C6P/;jbUg=ɼnQhu]pdujgskI!©)gDy5/AF#M.gD#  F ^b9j29]p#!ݘH9Nr I/ၢmr{hFM>#@&wX,A.&s?A!#Tn8p'"D&S[ըفT_M\ݺ#Ń9! 7h-ߘO=e/ߧ4)kRGp˸ 0,|ł2tU.^,;iOJ W˸=tpc֑\vS yZryױΘ{r!D?E|i{:fϾ9}]`gKH`]L'iNlPN/%T/7G?U=93{ O T Upr8K3,L9(G&<əka7JK/gptXRɲ39r-Jzۼ'e*%YIB3rTƎ<\'R{>uop&^z S+WBR4~J B>CO#=#Ah^IнDV \.ty<gSx^nFZ^!W&.If\+o/բ^Nqht^2^-+{ Cc4umSp_Y:U0|9^.PROƌ3\{cѢM>TTNjȽ I]ٗ*_ᝤ84<\gUCu@o" A$CumǮ8v8<[WI5%zs~-WC_ xo"'caY33A^RALfB4#0z|I1e.Xiq܈]eoA>ҊBC>Z#b"wnbzZoUV|q)fM'׺g-YaGS)1u i9S!8av 8ޑĥ=@ef6yT69b^NXI3WʅomDɍ:wp;=,0<@FwM=Ж  o;`k(U5dwJt?JCTɪML|xn7:2)tN1Ajqen+mjq VSoQjW;ts;D6:XP\u{;{֤3 endstream endobj 25 0 obj <> stream x]WWق]ch * "ݥ{WwYQѠe<''1&e;3bEiŢ$ F(=p(b4+SL1rh8b$QW4{3*b2`pRX߀A#b0C@RE)X %X`,Jq(CIFE@vT}5O ؤI.9 ~Cq!8Mw I}{i$At*-'RL2Nu[  > r]j2 !4y'C~S"@~!"!0k I2:t+ !;02zu*ǩ,Ɗ{Gg&ەDy ősqR6NݝC/BʛPCь ڷk6~ÈD.L5j$H2.T, Uinbz}'PxrG0罛NmL_]Y\¼t83͟f>ΉV^nPy[cǤ 5In_QΉPOX?oi0 hn^d?P Js(@uaשZ{z6Iƛh~DmAt cqAjc ߖݔ78Ln⌴A& q1ΨVq㽟Pl/vob2΋>p1⚂Ql`w :U =X&1i#@ނ̲_23d&7 AfdҼtn^:7-OB9Af}l}lŲ24Lc7XM'_>NSŲoh7XLǀ|~c>?Ov%2(o 0ά<Ǚϭm3);y3vgH3̓; f&qR"ܬۧ~7۟I a?#a3kBk=x'){9Y STKxn%WH#N8 `J(~CH/R>IJR|_A|h"6@ҢF*_lPĶq#p`u_7_ړV싆\^ ށ34뽃nѪɐc1y~&(P]@85H:+ M[ދSl5z;kWW C+*,S2E`*]Fx6n c7)X >icn>=\Bt,Ji[\K E%"JsPa}\KU|_Aw_ 4JsPaY[P+,U /P*bOz0vٛ\m 9/an4HInHAҹ iϭ@ ꋔR{@ZsbmǺFߗAj-Zfcd=L+s'CVUʂ3eQ*Wk 9JACA!<-BZQAy|+i0ccS׾_e OW WWrcx<+( 8OP:+R %}f'_ FY L5+ YBI2 Qg@}`~,aUɾ_Sc+(0BJv!ac_D}E!#z_+!.fW 8Q3qnB+FGł dW:"H> e @U #YAUܿSv"Ĝ^h4reB z`]+_T|_A1@f)%00aI>:'̃O 8[n l@}>F<`(t𳧥v0Rd psZv> A My qt%z(׃B+(% !).RbMSLŐV˞}N@Aa= R&C)>ϟ$2;Q|_A !yH3)a"N0ڇ뽯|q(PgDpm vBz҇R X_[+(]G &*-f*\/Bz}y(2q#W@Zl%rrKjͦ!0B1zW=D@Mp[j͎-LEi1{"גp a" @^ܴ>]I~3j0f;iO(Y}&.q5 }K~Yv^` BcHW4E.! H vmвmmc׆qI~c⺔f[7K>)΅VAEcq;RnL[WAo׿_B+:02|&%j!Ah)qBpB]O]VU_!7Qy>)y|ueۼ-s$b_=(Y`DFķ;,>)Qi Gƹų}n}P)H%\[;lv^!*{<3s8?\c \)'9iَ>sXdc`-&B25Lc6ٓ^j<=EaD7ua=hܩ ¶4suw38 '%q3_?S=C t vW0＾|\:+-ss;ͨʼtn?!:'~@a j{E1juMҳ^0-) myHe A p6yo'P s"暇".sbK܃}nb(g٨v>s(8XGJF?c{d'V/aSKH:SR~M ù@IF9N%i=s L$$) >-0S[ )9}i=h}7Ԛ:(QluOMڼ+sr :1LqhW@j_5!XP"kXMD+28tG-#K`WaiuM`#aqļ^qdq@VWhA5WŶYJgEzCd8_r^O >5jaI3Jhh(Ή~!b?k(D@PA_(o߾ٺ#~( [2GǗY/K1}zkx[JG~ G:xith꾞ݾ[*\D_bXyuv5㹕Ss !`P!z"@71cL}_Ft<` #6oF]}gu_NmGB|YNqÑΉz6:t69$9=@XϏ<)QS3ǒiѳeM;F=Noݎh{sp7o#ϬyZQF]WE2RDeQ.?c|s2p04W.$0 %?b.gq~NMG;!g0ΟX\s2'ᕋYo"F<Pѱj ?PDIB[,| pAR}CJ{}'DA. >ٷFW/M ZaP$eX)ɼ:m{E)" mt/u |9M IϪɟp0OV%eqrLg;5WRCs=':ԉtj^F8 jFŃm oXdF]wɊ\Z8B኏|0}!r6^,THn]ҥP n'֋@Aa?7 y T輨·>~FjC ġss1Y8K+t6%.5$gQ4Ο?Qˇ<O8n/uC4|Xkhβ)u4JA2@h,9d~? y%>jzz6wtطWÕ,&[Lui ljhG=s' ?DL GXghĜPG%ֹfn{Cbkzϒh8bO'g\!W2y3T Q0I7ߧW7}!PE:MI a۸l~xOh%_?+ҿ>uw86r{l;|f_\ @ZSłҚcC+$Do0-Qbd {5NMxt!5Gd5wX$o3Anl/>}YwtwC1u\ͫ{J{?=}u:c';?]Nxi rR-#l.ah_ӄG?̠6sz$|Q4(z{Ɓ0t?we'Iڱhh@ے]~±_ +T;ܼXM[peG08:˼twe#@8&9'0YwWT[tʝղ:bP{o,8_Jt`>R8#L%YDWMrx|`"ܼfMOp[߾}~ ;/6YT>>On\\:CPe!൧ ÑBCi^&j0 $@x\Qg]Lr:N)?MLm$3e$޺h$b?VKF %:IG]V#|??(tYw`/(˫}{lمg~om5@}7|<JJ>p5c%AO]CF#&`7%tKvb54חS~ۤQLK poˋ1qc97hQ|pq.; fwN:tKKUw_U H, {0vT%#$P'8Z 7&VQڙ'h]UT9 ͉2C뇰MvOX;(ɖwʉ<00K-)9/ ?' Fyyc@6*c60͏;[{凭UÜSYzl0(XSl.έx5-N>|(6Q[ved IgCX%Q?gh;Fa5"6W8mQn֚''rb:ﻇku$}ZFvrLFm[)%p0]edW~bfԍ';j%Fp( _) *\w6kzѩzt 2ڡ;) 5KFqP-g1lN4#^>#/0VnHb,N~R gu*/ҿ}vNGb/W*9u]m?H9$Oד>}pm"+ e$_u UZ>fc~6-jeNM@XLo_/lFpVM Z < .析=}+:1Ba6 YFK5?Bjnu_ jY^v_\]-I'x޷ SHnv*#`PS`/Fr[͋G}ѰqB|Q;op0m2H~Or4|ٚk3`HA"5y;ߑH.yc-U5=$8CN- d K H{; yֲ*$*~f``Mo)-ob50{Cij:xX;C8؇Jm2E+e`v[+7 p㭖=8'lvC(6+ZN? =j`_p>I<~z8ōAF*Lo ި :P3RmBRk3r 8ɟ*\dӌ*N8E 3w_lg0k4b!* T^4ypk>ffÉ:xV:H :oENH%X`4L)@Y0*s;q]5)NdS>UkW6'&bM;jœv ÉBUWm@W'ح9ڄyq:uWݯȲjk&Zy`T]`M:ۑiԶus:Fh8I9jMÝ3|-ed"ŒҮ f8B(@f&sG/ 9g7'_QApdyeR6En !y("|b} OXį@ B1@Ir@I!8H5yOTo ½wNg&\+xzqy;~"b(z/ܖ"a8K$K@;罃?,G{m$d=w;1(Aș\J|1Ȼ ! Ε+3@LRhsr_4􅊥]}SX`֮'c } E@XCs8_Zly'B}SuҹB˿H ެnK:QPi/s0 rhr\m:Dyk1.@>2X RB@.W=yu?7<''8ve?8֟b)[s4:vfudiw! Q9% I1 a(8.n1!{daG~[T؊2u|ͭljʙ(9/iWZk]bhy1{^ ,{8͉[:;y}2wʴ^UgjIB\)1|j@)El<3lxN}Y]d-sYMp7F?^g֮w:%b5 §k}jmZEǗ"O^f lڐ'5:o^2d( Ήi/gD d<ٵp?5OVO׽-s ^ N֮d<x"YNDZ:BG5=ayB=5poBpu plvnyAُ[vk{RMFU xHOkBƇuJr g0W}Šqbqi=>~; >32ZY=Sk{:!'?U(*9;,NUDJ#|N6~zg?-DM<_Z2$pcs;0mcxq6y3YNS<޴gXbhX 7ZSp+_ûE Fe@Fs%pcDz[k+֨Vk_3;2HV`$&A_F*!b( &5=/FV/ڵ&/)鵯xinT rHSx~ P5屳 XI1$~Q 8gL2Ӵ4vO|I'k#7ɶVgl!cu6OqɂP2!3t~|GEd`avPHLaY}j.sC+Sq/} $\p'Wnd8@tI/?'֋Umuќ&1罃#VkAJ_Chi`ȠIXӹ7`Cķ4_die%Yn bw_y~9s)>Y7W?;:E2i8|7&抿L @ |Y'!rCKGJW0C+oaft e4>~oȃ\`#a'ظ~K{tOʹ:=3T˳wX !IBP śr&Zw2cl*Ak1 qH+Kl-_T}ub)+Ve ɡh)mI7o*bOE1*U3C38 %Yc7:؇愈bā ?"on+ yR ee]MXbȮ2WUJ_#&C2-/Sw?%byU@:¸ r]Dr'|߆٨WuP>mK>lREjSZ |p(ü3[԰a#rmU-3Uun*sJ~5L =X3{a !նO\5,Ynϸd<WC말zcX/[sbEGIdD@n5E͚> )r=r $i^f(\ϒ2j v@5aϖ)6(n|蒈d&NNEdp@)(cy=LY#Hi䞚f!BO*rC$B(aJar ]"*Jq j>~'Yo<$!""h!92אh)=; ҃Qڒ*StpyٷD馎JzF&#,? 7rC٨䆊pJNC_Hەd#@~7įRI\冊PCd1٨|f p!Pzė?R_.n"/!'i'ahϲXVxR @9`v(‡(-GW@zҋQu{&S7%x9<$w82 rxW(cFk4Ͼ?W!2)\}ohU2Mmi//(PC/4: $Gf" E)aUJ+Gah;(cBZ@pcpBUd$%!Sv 7 *V(rC9(AF5.#=wAߑ*1xOUpܥ?^'DDl I~ P{y|C˥ ?d$ZF]hE͡?"Ţ`rP PQ٘OabOVlJ[X;Pѱ'YxD6@k;,wr%=ynuXkM߉8&G0~-8ZWqRNW^@Sg?"7 ._g5k)O8bCRGF* >xf}SQzeOcI;ۆ X >u&~ G?:R՞4zD+0AHNMrj}eTxycmۭ&C(F#B?Q?*9OA ɒoN Ze8eD@c+g0u|y|O3;=< j;ŽQM g*\_2@(q>;7͟žֆ_{25 ȡh'bN*WcC gpc+)bYnwգ[EK \?9!WA>a߾KȤ8?&2QWʌbOTIlojY"j*X3ʹkI}y&P˛X.J>x"` /d`(3&ݼS4ajSwχ?:?Dُ"~`w/nDM`FTmB=3FWgź^Lܿ/F2M;= J_^ATGV+:?bc Frɒ(oy,4v/|R pj&9HIn!R~:$0w m7Q2nS C%WHL.qEa+KFqJq]Ss}ü'6 ._a/h*%ܙ)u֛,bol 54[rCre>?>K+vFkۯH*UmhE*ժF㩨dPAW_üܐ2 <%8g_ Lr+FFr*q]9xǙZ XZBfL  HNCr)ʧ1/a~IagJul`5_򎠪QIHi0r_0J aP&5b 'Ή0ݾcƟTd+)K(NvƬkE=p6!AoHkC> {p85TRTrrrr;Z4 Fc5BQl˔Q > \ܛG2PE^ޮ8Q©"c"`;*\3F0T}3du_.? -sWr| ˺SO5$)Y*!'-!r,bR3ΉI)$ ݼ.>k߾{n'֯Wʅyܴp3wBُ#z>2s(ü?T6ޒ>D4GI1\AAޏQϡH q6X˛~S˓,#8A*Qpwjggw3ZgϚZ߄> Vb)9AP,0]Q\e4ژ۾%偦o@Oh7o*2lP]v{7yڵ+mg(`njkNZjkTGIE (D{ۤ+7{w"JsDgF1˧z%L#|j-GF9M7S}2LYrx:iGI~ߖݖF~,Y8W@=b»0tXͣhW7m/3 0<|  Ԇ^j7{5&6%Q"@(^A 3EtJ?g CIKF$Rxx98!ud1Bψ JpV.*@0G KtsHw$%kNFKFK!q(,ĚbP^$ > tR^CD ^.7S,BI: T'H2z~A@ꏦXV8;]bu| t#:Q|Kj. \#X`4:o $Mq=A@O第U8ryxRS}{RRMƕkY~[%ĝ "tGF/" (Y)V†=7Q70`6X&$h/  tR_Df endstream endobj 26 0 obj <> stream x{pTEBc @2{>ww!1h0X]"X G"ZqŬPd:I<ڳbi=:P\PI;U[}~ҵŹn_e[n-XIi1πwrhUiz3jkUQ;][+mˬ-T)׵{vT@~yXU ~[\N^b+Z,dY1^`Ȝ>m^`6f'? mq͋N)[}wOڙ3J*6bZYZ"wBg+GDꆶ DquAQN4h}L,ڌ*6@ `Bi;C+E<| p2~h#,x㥤; _tYh̰BdZCA \@)&h Y4=Ol hAP^Ft 5= %`^< Z ji08u&^.<·mts-^V@TO<8PN#;ΣQdC^k<:-0H$|Ȧ^P6j6S-zqNgi$Hz̺bjҦ^)FiƼ)Fit2D(͚5lbofL% NҌanҌyH8ifqE.Sn[60g8d|=f:@Uʷzϩ(gd[|:2 Z}:1k5.;zY#ЉQpLCF&gSeIMY[F&  *Si1_@GEE*~蠨WH-::%6NÉ^mGRjF{Z$%5u茨BK~TwADw=}`tIN蜨h))4jC+%M*E/對JΉT{fΉSkt:'*rtNTtΣ:'*FWU9)[U9EY큎"V  3 F@9DZT :f^:f 5jjN"Zvuj tAC͗YVmpAUйps.UX+ߪZvaUйpsZ9йR]бsRTXع]PYX9"h X|zǬTG!ˡSV@BO߷ZSݍ#c{ :R<}W:P\an5:P\X0+:Q͢CbR :^nZ -oK%phaut8C*1֧~BBɨ t>4l07DT>.siVIqJIɧ]d,AgVI]&eTBAcC#<TsT ::(&SJ%eI1Aw;!:)"F+CGEV.@gE4[ hԇ{VJIuE -t[FRii:yoXhTPҒNou?8R sEŅl9Vn Fܫ<бcL.B]|tX&( %c] BҜcޫ[%$QF*!dz9nExJhɫFGY*I/D*!$%揳/r)XNV b|4pL3ЋBR硗˙$ 2^$wbX*}T;*֘U0fRY WpUN홮UBݭh^N W1"u1ؗJņ*!̫`mYTUlWݑ#1 L!UUlky[#$/otI.N"$5I";ZBYU_ n?xcqn*ח ] &}WØv^-vX;@ȭb^WƼmZ٢enđSvUH? !tةNyo+Mؘݛ4WFĝRUlKGABV&-]U짮2UőieI> G<@J~?;𳷣Ulmyl^7V{+eRVl-f'2n!g֋J~rIP}9LbuϞ\[?\a-2gg/JU5`ЯV{վN_-.o8u:Ǻ2> stream x][OͽȺ⪬.f2xEQ( LrU]~N"˭M>gdN399ܹ3P; SkG5S!?y\1kFy!9= xD[[,-d?X01 tbc6=${o14:ޟ[,zgIb15* xЌpcFޱ/z Ք0qW%uEPR"y,wMA S[ X|-`Z+9M!LPStYlK5DNdfƅ\WEcYVV ,y5 "> L=5~^H$J=>4;i\R;~#<%Skܔ!69.jm]-:hinÑWJO-:u$JiG@vg#Pm_,,Գ< ;d/{CI8)/ܚkkꍂ gmhuK;d~&}/gd,|Z1UlaX[ۤZhkT 4oO[[~,[ Lj+fp\$iTwP#CgO^:hklZ%b6ݿ>PϬ'앴Igr|9i)2Jׂ\*}V^ƥމ~գ޹K؃o٫>R h @440^ بఠxF& Lg7',N{!{麱'[@YШ[ND|%M%LL͋yEP1 4 +3bsp Z*(e%7Yik9i *\]E HՃ/e5XP=DNNyzOaר'{%m7>,͎ݕ:68%`Bꕇn.앴a @|8JtY fC#NYuIZwZgd=z'?4'VlGY(}K}6\d(}eNOJskQ+ " ĖCz&{{m+N(t p \C(zgHѡ@C.WKtNy N'PDm%XЛ_gנEgEdMdg||類%qڊ"bwjo5ABW?\9E7ռZodqDlk"W^~'N#1 ev>iE٢s碉lK_F"^>/;ŀ ʺjOl17][;hȺYdo<tHcAח*qMu@Y$ʭ?9Z]Mj?x6-Ơ~ʥuCw~>Nd6ޓ."ϜWY-c6GeuvNjD }NDza/N:=廲 K"||"{5Ț0~vbN8h1xF_%!wZ^Q4edoӅzIFt>aTE .$@Jzyۊ Iב&C(} uRNw02>>,AZwP.aC"w}Ttj 4e(0th s. 5=I[ko^P)M9 s҅bkoA4ֿ**MYdoNTOan $2a>Z)j^q Y=>*s:b2Vl/5 1㺘͋o 5~hwv8Aݟ`bZ%Cr9 avĬ/"NZcJFu;ypjRYX[!=+C&f];.5K_vؔ -9k +D2>|%J"+36_Tg ݅8$j:+g䷣ U["Ȅ5x#_n& HUz͟|?;}V/Wg4ę*p`"~#"\%j]ܷ(bi_j̦߅|k%CVp_}u:*] j.{.oO o#N9ʚ)n{KԺ2fqWT 4',0[5w: j0MiI)hմuXa5<&7!QOԺ{[I ͗򿈟gjA(tByw˽h<|~̖mI^n?P0'T_ئնj|v+Hak fDɿ?px.IFR YįDmy'3}{:9QiGVDK ]2'"KϬ I&=k_|Rtvtb'Q;dv \U[4Nn^M_qE]GiSG)p\vd{@5q-%jSO7$stՄSQ@ƵqoGgH[}4uM%L9(Mp5SYiïFL$iـK( rw$bJOZdt=ؘ6.l}oDA:gEJ^wO~p@C;%ւ^bgO<M0oc1C@Ჺ7P oUE7[2jFuuqO~|L<><J]el4 N(&1VI˅b*ifrxn&hf85H^RO7.| FB8695koG=uyXj5 NuAkCΡ7D#] Jn:ӦNC;7DVrndt]"fg5p\yA[BiFTQ&k7iUڌ:B+hU[ge͔0ҷŧLcpMƌS3E4 !240 0>['Geg?pF+ӂ@םAg!ԓvBA0!gpF֡?H20~B6"3I3"u d` endstream endobj 28 0 obj <> stream x\klTEm.DPyM* E#тJ$QPI[QG)5&4D@"PHE")P4` iJZ,D!F-};;f}{ܝ9۹9gfMxͪ=3^9p 66 GHW*M!U6m", RQ?0e%^X6:@lܺq-Eqeo_9=433fC|)9p]o%j%\"V8<'I%WN)5P<*^r8CVo) qE;sHN9r:aGu19SbvY2;ŵ#Y`02C]N)9/!sTӼKsɀ`H,枉/ljSGlɀָ7IQ9qhf a~D;^ 9kY!ɈSdCRr2BZ*bCQ& Y"^[M꘍fڳP? :G>to] e6۫D&(B~꾲W зk5] -{`{rJcSyɒ) GB!-(8M5P.ѰAt)os?:Mȓ=&^!WYY9u:@)h4B"Ʊ/!'5XE9`V_b&xH#6&Qs9BrD/ jq tmb܃Jz!l (' r ()c}$B  1[v[փm9iږi25 KZh|AN0jJ~?m!xtP~#K1 {& tax*N-'?8?$C3E`)Blgs*bw{k; zC"eF̕/NRN]tۡgD͵q39S Eiu8'KtoIH*lba0>rIOXRfAQIA8SQ:{fy">Y!k JޚYTX;|}Z;NfpD$ [r(V:0ݚlG%ʒdlz֓):giSmv&xuWmb/`Pn JTň[V1`a>jw)eÓz>6ċlуZ~bViQ endstream endobj 29 0 obj <> stream xnF):R} $ ,؋,D@6:kg8>B5OpƎc UfwuSW1wkGƻ\um>]JUǟ޼_wWOVg{?|vg?庛.d|zmzzꎷnU}v{G.oWg?g/|ܾgw~s}s}pɳڅn[{Pط.{__ܹmk n/?a6\jӞ|$B}5őxMU7{e}hgdKwd˾αuU]g#Br1T)=U۬ !T{J!ֿ jG=%R3R"R(7=r}coIOZ!U9 X]ιݏ*TOmxQ6ʦEy79̅~<gnV_O)v!U)ޫ~X$h6sWA@شK $jj6p]n}M%"l>Z"ԍ}}lBK_D|trS8s| Mnwp0vS%jkꆚz!7婩 v6EBt>s vSS} T0Er-u5i]M|xA &Y©ݶv{k;yd0l;14c`Oy;d \VJ +)BA.B0e 8 d;8꜅9&). KJuh^'kv;&56 L=6@"IU>'M&QǑRCM]7155$h PBAt-[;Эj6TTJYma \;T'41ș&^ 2cxE~aGxX`px@sqEVM`#5dI6Cf`Wp10iciGٰ@K$݄e&,hV97i&oS40ѝu31M>xG_HLoɲ`vegO%#:<!]3" M%x)/;AnoL+-hhs1hm8ǁ(-vs>Phbйɀ3UX$4{˼&x#55f }:`.x!guᢝ]>74r[ Z]L#ǻLG !`ri $1S4·db`D`Y)AS%It1;{ܼ] BV|zXo& \sia.$}&#)`^`Lӳ gؤgގmbw;6Yvm2aɾ]GP]:ȍ]`/RqA(ɏǽ~ewl)9RBL\,ŴEdit£M $| ^uSЅPp =itX.r%`];tud9f*y=d.>,v _q8! }/pRpӺ2I'c5!eq@g4*ؤSm>s6~ao^b`{ 8/Rr ;Q$0 4hԄ*)YXLYrDז'$YS sNqRrL7An_lJO֝L.DXY%X,We53MjK]ơ/"|\RhktśG P\\׾;Kg_ޤDjjr9*AN(mg`>t3dO0&T6rL2²r?erz9M{]wuf ^Q |GW`ũq|Or:{`U"vyGGu+2{, }9 x !JlAѦ>URDKW7VљPOǃVU}̚QdzV| z ɠ&8ٸ.Cy%-3Z]91, *ü]'Jj41 :! oݺg A~\IȾP{M@o\J?vCzI}C;NڡwCDCmpy@k"@H7qL׳1:!V}Ɇut@mX0GQϙ] %?;D*Z/劑%A_7Bq3-r4Z8 {QEX 1Y7hzD/1@s;f=Ђ7o `8AqWwƅt6.xΑDGtW5/e2A),dG3jۖ,V>A1ʥKA(z$ɒCM*m\5(a|w +yNp2%:1KMGA&ˠ\L$;هJOtsEAt:n*-7EDloZ¯n)hO -zWb$D\~{lB'yh zz RDA7!,^L> stream x}JP ":888dp&iISpX\[[ IH#Ź /..>8M$q~*H0 Ӥk+p} 7)> stream xSSg_3= /`2tv7elEȬu-mB-P)/"1 &*@Z+B[ps$5!ɕy2< 3^B!BHJdvn^o9vٲLfB!BHjlogbRofvn>{s^l){&&uՅB!Iv}Ѯ[:qLLfoޜ72һ- K>_}=dvXES2E[ 3,9{s^z82@Ʋqmt>0ʪڑ1gb([!첥}ӻCTK>j)/Kuzƫuz+h-r ssd@|>(kE,i¢Ի!YaȘ++z&&L=X e{+nR^3T^ۑe2CxAK:F7ԻOJ 0>DžEicJ4#ޱH?J݉;K>_eUm$s^ g]ݎʪZqvx&&nd(x'b J+bdde)fA9Ϙ+&ٹo=kCWHB/A#x%@,eVh5h-% jU.mWDR*5|>ĤEQMK>xx%'M-JRi)>T5B^jq\}xg;=+tL2R*[ړ󈱯`GJ(XXX=7ڋvٺAQ*Kg7cEmbB\F\Uba]v([!=pvnV\1}m+eS~iiks"[²̃9xe2e2'Yz\-x%@^/C8hzV-Vhf̕Ub *ꝑ1liS&/eO*Vi݄&JQ5LbIWDTXzДWhNxTT9ńI醖r)XhLLJ;%Q2J Tf<7=;NG}12:uvn^)!xerD}9&s\g(J(JB Zʋ_sTKM2C>V(RN4ڹjVSOM;rS6"XuW&L#/ʕUQ31R;*;7;+U&S=r]+eqUMʩ5+)ǃNB ^ rzSȥ:W+TӲ)JYR+hekr"xeI$y ;^^)9pF(`[$kzYp\+CU {*#$? xe|ЯTK |>90.K9 \׎sW-WGg* ^GGdkx%@tH[sSy+<߱9 އxrAT,70xea/. *+bd͕87)Jk+Razk2A+S9TًW"Qt)'bUh vR(U漲vdx9ZS,fx,@Q{R!k7i; ŐʪZ΢]PnaaV>~i Yz+cGT݊x"/@x%5WH+cG+jfUmnikޜg)&x%Yi)Qf89=㭬 5dF\^T֋WXF\rg: f2^1NF9]"F,9S7+@_]^FXD.#/Vn@:W&1XD/nZ,/bFA xe2Qtɒ ^ ~IF L~Ș^d<,%&Mj+2ɈF\I~\GV JL2K>_HZJL>xs@|+O&{>y҉yxed+9n FF^l) b :L{eK[VP"{s$ ʅyٛfn DϒWYUk(2+(K za+e2z%+İY&sފngbrzK!B1~(V#x`aa.^B!JF; ^baaQ\!=CYнBJ;Lf[ ϟLn@W@bNwn @W@S]n @W@Oz7 + E$YK),@+ QR JHcTE$UiCH+JHc69W땔ҘRe2W4t.WnsޭHJHWB:t%TR GJHKR _JHKR GJHK֔JJa^ ǚEҏMHRXW@QmVeᖪ߿xwcR2mVz'^ ^ 8JJāW@&W$2 q LHx%dx%@+  W$2,9d^n@W@32^陘Ի-i^ iM[W7n @W@zS˖e2ek~eUmٹy[nT|e2?ߟ\Xޜ9Q4eǕ1'd?\X7Z-,,L!d}y9+%s-mC!$y§3>瀸bХ)G+_Nf%V|)ekikv8flyu&ޭ4e̖|k.[JXseMbz[Bw%$L*j& 1zoQ\<vjΒWhG\=vz뙘L\#c.{H31Yhޜ'.dExetzu2+|>qsݖD: H <Y&3 Q{R2tu;L1 IO7d r,yN1P0>Y&sgr[dWfoγXnE"֧j BķLL083^ޤ`|^yLx\XX䧟\z e`dvٲ7 pDKN&31wCҖL~uDJV@8O|#WBxW'2!@(eӻQΗ02I_WWriH^Rloޭppu#Rޯ$Ґ 80>\2YFWriH(^Wn`|^KWriH^Wn`|LsI3JKCBpu9h^Ґ 80>\d]%!x%X/x%L2\ `ƇᕋK ^ɥ!Apz ^ `|+ X/x%'WF ^ɥ!Apz ^ `|2^pDmxzҐP80>\IKCBpu#_KCpuW&. ^J O+YKCpue2_p$BʠpiH(^Wn`|/VWriH^Wn`|L3/җ\`ƇHxҐ 80>\KCpu#2RWriH^Wn`|GKCpue2tD"q ^ɥ!Apz ^ `|{y ^ɥ!Apz ^ `|2Ow/.'3x%X/x%L2\ `Ƈr.\`ƇvÅ^9;7_bvn^'^֮w+ x%W #cʪm,9u%e{+ I8oK>y-zDnZQͷ)ޜ0-9oOyEeUms`$J0>Y&syr2c@o/-rr KS=rrIt7Ds@~++e, g]=s'\$.1G\z¢xK>_YY&sO;\Otw;do' /9׹v/߻GTY?P?Kle3='$iqZ"Z dK[Ju&$FgbR71΄牉qrt7Dm!15zjW#27]qn[)Ɯy %]|C~o׽Od:t%5LmG}d9ko;P/sڟE8_>H?ORpj>r2jOkomqDwLPS;L~s{BTlk_ ¶|+RWZ*Ha{~y+/} ׯ-\uJdǁ7V37Vr7gx%5?8ѹ1n ݞǵН7E>yV2gφlj|{7&W[L3;hfǰ<y:=tztzzt?3+>>f5>س|xGf٩s+rJ~xaIZɂĝŕX'Gx%^W١$I+J r;P>AnaR^lɭi]0=0k(s޴EuJ- Zjft?"')N9y=1223+Hrx+޺w蕣o zn zJ3w J2])r 9aL1W\ &yC+7/lKh|}$,^ioΎt|^h%G.<}u2 ^Øѵ珜8ĕS+ŧDW~[ls}TGUh^ `ʩgmu-yE╅=-lZIz=%Uk=%`ZOUW`x%DBt^98Rk6u H4=˟$.LZe2Q2:gG;J;#n2A^yqeO񿂞B_"7-5u8rr KO;ەRXZ,;O5WRvml+{VFGv5 #:ŭrjQOWa#"vP.ˊm]MG==&2+Ht^y!^pNڊJ+:BzJM=.9*4GmkeM)SRsWm?yY5u ߹߳(ZRTZa_+zpʇW&ؽR)zHown܇s4dW>HWUqg ]_3ķC>ޗ_۶m{Ǘj^)N`4Gg3?,ʉH~ s(bʁ'ץ6*]9,v* :o|P<w{4h^)mqͱC<=eeŁrw5VG`hgug0;8$L^W2+6/K4;AoJ,Z,4P?Cv8'Uw٘1~+O\o 9:o xpZ&xeϙʺ g|<GS+n)^WʎwQIN;k:J+ lwe rrԯ]5u%Q wVJ^R[9甆QV[<=/_meŶJ9׉Wf8y,@]ƨR5lkB-*}rg~m_}_]iZ[ltZ'T<ҝSǵn"2:bJǓ_ 3Pˍ9>(wz+ v)ye{+/?|'rs𛶒-oy5ƚ+7.hXkơѯ̌ooJ뿨u_^yyv%EuPxӻgQRPZb;ui|Wo\=s숭$9{npϝsv?v#޶P^9rB M~𹗿9sPb7[q+߾wH,okٛve?83Ft]}~zojǾw*[ytq8sı'=~=<^;sXGU~Tع ;o?v^_]uԷYocv~dߗ/ Mr]O\?ϽC8ѽtƜ;K[4p0^9.޺<ӫw bw@P~W Tdž!&kӰض^+T*կNeH +ȺSn\r3l++3Ujھj{2W xJITNݬv߳|r~ϢT0xe|+ e/JTzJ땭oy%5֨2Wghoq+!&g JMɛo[ּ i,[::#?ݹUٹwU+mվF{Wi޴uʐ+;y=7W{*U 3o-A1gJ75;|.Mx%@Db^OvYPJEʫ*^,Q{uVDqdפ)DQJVQeiW>đ831'϶V97l|R+mkJ+6(er"2q*ׯ\W<>n^y5_z]ܿiʑWMR.9V*o*s;[/, \ \N% '_yoW*wJY_|}Mv۶hRΔ|Ɵ^m{M_.8'.ߺ<ʧ]Ы_rſ[!'by;#GoZ^+8R땷FJV<ŪJCʋ}Px%@jw<ը_\wowBhv7!2| K{=;J X+r#52ݥWH Z*gU*#:H\WqA^GbJ`lhWY)2d;kzON*"RE$K*P]R92jxeTz\sRo*Ɋ+c[/ {mFkvz*hLQ{Aʣ.w_Q^rޞ_.rq+/ Ws@x姫`+NPa+zg+oJl7缢9'^yDvIJl{Tz]G@*?Rzq\ MV+;:/k~~k]^Yeָ+m^)*`L?x#ϳGg`#v[|JexK`wd뛏JH^0r 0gYE|xe$F7oO|RYS$GM"!Uf$+3zLgQ9EjR9k* _)LWlk$W^}Є^YT;Wzeў>G>i8 W~qç8| _ƿJWaՠ댈[uFWW ĖO|cM3RWλni.7mQz`vǥ<CAfoڲ.jr~t_ϙ[>?*RH+W?3]g*,'Z?W5͢y͇]7ǽS'/m]d^%Bb )4RT댨F>+ϿrPHd>Jٌ1yCIW*-*3JW)[7iK[eA jJSK˼=Q{ei]U^ZbK+]T^[i(<^)WȽ2 ^jʌ=+=yL{AR\WFxv.OW*y'WQW>qQ 'JuJo_tgoEO-ۭ׌An8۳pGxuR؅M[, J٫W{)wdjĥl)^iDך|rĥT0޴8lwFR*;aJ#W}Il~Q+Yܳ{%%"o)y_/iӧ+WZwJŶ={ +tSzo^.W;+wXߌ+KvdwHB+{WK|~84j^uF+e)l%[jfyzR.+q!2C+eGv!emɓn Um砬G+WJ>rZuJmq)Tvjf׆m2r 9 W^+={^91=jy{bJ9oKʫ'~ \D-+=+Kʟ׸*?G9omG++y{"ʆN}Gʞb=x%@\2;/0H4-^=^xOKspǑ 9ڮ̸x#ܚ溚:'FʅQ˶ʊm]MG}ab}ɑs)JyLywJ*o?P%ratT.V_23V.(6w8'g6drp`C{g߳(z*R{s-V9)+ܸ1ѫJH͗jiqky޸xeᕽRt{啾N.4ңݷz^Gŭ-WJD+jEj*+&ќQn JS6.Ÿx Q+E*ٛh eL;Tժʖ:僆jGxe=J a^AJx+-n tTx=<ƜđX惽oP*mN28Se~M A+=ڕWTZ!9)MP=.!z$UOAYlhB*ʨ+oh~RG|ll?y{CQnM=8sMz١#[w)i;unXMz\W6REt??=40R_{+^),W(c~uo˺;vyFWWY  \}0p5r|16>l=ޟ2ժJg'1֍/:Pl:Y}?wߴuplP|ڎ=5q-2P;W$apo*x%ޞ^ǨJRuRiv}Αs}NPQ6╙C\,^*^W;q+ t#.Hf_C"v|qz/W>xPz;Pz=.[݇QAްvjȽ7~W*f 啾__j9{|.Y'3' vީ uؿ[>x7}y=wW޿^dp+(Km>?+Ú^9ekD\REJƘ^1+H֯$xeW+챗\LD&AWVrm݊/W| { {>y?|xu2>^)y;CWJJlيe7KKl5}soX5Iw׹M[lm"ʫ'n͊Z^buⳆ=R fuFW.8yY +T+O|7pbJիV_s3*ỹm?ػÉTdJ}+L`Ueo?0.W$,~pn9|TNg(o72:J$xWFGR9oϕG_]84{]9lty{n=xj>Xr[_hjT^9ԟ'c>{W>-08(W.NyϫRfOP^vԵ;a֯^p\'7]rW^971=71=R3ΣPJܺqwӠpjʇ0 / 9skgJQgWz^  ~X фD o72:J$xWF^i4nhpZH-L# HRA^GJ# ^+?Rz{x%^ Z7p;p{gzQl3(DE> o72:J$xWF^i|伦x%@!R^&79ƌ=g BeUƜ<*Ó_hS^k!+J#5W{~]nF#=6y-|Y&suDYmZjosqC9Ln7~-#c, x%^W+{ E Ʉu-"1'/rfCNsʩ%.޸jik+Bl+[W#ڮ^el:j?2zϯ4x%^G<眤< 2P^*6+\gk8^HWtN9.mVvk)U|MWƴt7 Ɯmb-Y&?WxeÆ8>H!LSP8x7Ux&&x}HR0)~Ow{z=B*[~DUu'j>KnwY-d*,|i6i eoΣ(y0y,-,-NgDwu;ȺFʊmٛsbɷR ͋X\=<ɕUĎ9 x%^WFWsB* iļ(MQ?9Ue{+R7U}΁Ť1WWѾfJ$-]~4f滺-mzk{k/fC>2(Hs@Bv{G[.x%^Wf.}pFeIm{.r7X6kEhްU*2]6 DN#mg:n? eF7_J\#UFze+3Eh S+O6@2wOL[#ˡyC!AwYЇ+3E"[Mf5`E&>һXNϬQ@),2b*n>E╷B")׻`"XJa2ީXRX0+C U,U\M|Zw畻]^0+3H`EZn,!XVĴa-IJf,`4"[C}wkGƜsx%D?=jΖWn$H`Eb.  d>^C^""{i+_i  ^ ^J Xs۟6(cڐ?6mQm\ah|镊n>w֪W>^ˎ+Y&er;pB[#05\d&x%z+ d?[mڛn<Tx%X/x%"TJ#cL2)x%zϓ y+K+*rE0 HJHoT¢ޯ04~lvD"sqY#Cᕙ ^ ^JHKsUVfo*8%r_X/x%W.|CJ}Hp1~N;kʫv_J`8Lf4Saoװϳ(yŖWB(㕳s]ݎF{ bwu;< }U.ٹ>ީoO%/6^OX^s9:Izz` Тʮ2rcR' ^$+G\|!$X}΁6RDxȘkaޜ֞v6^,Nw9"9jI(O8n<^p3rc͉y)CXv,8P􁎜]HbV`ɏ$WgubOհ)WWcf{Ꮂz(d̟pH|{~GiE, x%8LL݆HR[e2E+/0'Dt8'Sq7^Ib$*87^ aXXXޜ9/^ DuatTw"t%JNaXB|%$ ^ JLON8-+$?!^Ƣ]#&-B$++uJO_B$@Cuaiqaiq'=xOKLPJP$?!y)-֮nG\ ^$$I/! KwܳbTb]9~lHkD:z=qѺۉWB{qGrqܠܠש*31i)nnKloEw]HW*+ {RKHz,yCNŲ]j^OoMs_2WJ bxy^bDxe$2>_xu LLvu;Zڣ$xeYMwusN91TH-tTm^)Ho4yq5;b{)* |$h6H=i{iYLN0bM%%9lXN1q^y%dd N{lWZ*W zWB+ z%x%$Jz5JG\?PiGβb[V+ .^)uOҊҊ} ^=l jq%U KRK^)\^^B@Cz22#Mhw+!.dw\Z{ZRfbC]+!~w|z5j\gW;ȹ5nE֝Knꎕˊm?xYTb4Tƶ6F+8~kk?M~mpʗ.|źڮ%%,sj 9Y& J1v*4C}N3q#x{|zw5`L핺dvpH)}-?PTq֫wLY&|klj+s-C͎C͎ǡfd__EM~bkk_]yk{S@|I/!+ݐ+E G=MIܤFW*es ?2UVjuRz2`JU{4TKv}^*+A+98ޢŶaS_,Va֒ 0յ=\0$-Rc-{ZOɷ+ӌx3D畡{>.cIF7l[4=I/!#Y&󾊃z7$&b.ZG(_,ەw1W2={ZDkh+U2J/Y&s1G|.YY}ḷpCy#.aG]x%$D{3GnY[M9Vj:f-?PR['{!) sUme6OCJ h<|R#:ŭUI,R[t4*OEWQѪG+ׅaҰPc_`CfǥaփT^)g U){i+QzvQƪ=y[{\H,H(O:TcQ6V.ࠃU[źf7mmZTZGyBUe3T_qϋ$_h[TlgL-4 h7=Q M/!Fo+z7$&bJ#F++^^sK{r[SJey{7Sv]c+rrkz={ZdǥU>/q╠dM*7lʓ[T^ٷҧ):.[{'הʫx%ďD{vy>gQe[v"Np=[j"|^]MG&)n.+-ʛzBKn\˶mgS GT!;Wk)C9R&bUy+6ﾔqbWuJ3TBIT*UZ}ʧ#ۦOid쫶=W54hܿfITh[TZo!_!;LRNt#J HW-+F EC1x*oRʣܸ? ^ Z!^]ѽ^Gzr#k[J&?蕕Ieo"wQ3T!eeŶbM[TR[P2rSyLrܨWyTYw*Q5s)ol+}by-d^b>G-է[~Vuisֽ& ێ2rWJrOWHY4܈aE*E &q>Bwd{ڏ GՍk~^ՖtJjRT<:>1Ȯby҉bF憋S[Th+I)ԑ֧]7>9^dUWcl.UCu(\FwѰ'Qg|Yŏj,-Gk RI su9cO'r}.n(M{W6tFQCbۅ2b'WV‡ ̌hL+:5o+ 7̚nx%pu_ZQz.tG^_U*1%^k[R JKYIvL]y%8ގ+uOi^WPxeC:9w,ގNs^Y77=mThx kB &ňawG2nOݹW؀l!~JP^IYN;Mx[Jұ `]y-5ɟtW2Nҙ+$6^Y+J'R>ψWbхuuLݘ-bU4JeqxUi+74,mOkx0XiXVśx%A&^frdc&f&/M/Vx܉}rzp /^iq}JqUJClv_)Q'fz4/Є ̌X#X~zIE^'F^RdDܔudHy*5# _cxF"I*%M B=y=۱蕺z%m홡tPQޗx%(Ju_RD:iꏛ/+i(i >C_Sh\xesx+I7 RIxt03!ldiS(95xE{%iF[tE|=1e h#:uD/ބ+u^I"E2| u]$55͢WB6Ҝ^Ϟz>ejiꍕBO_9kWWCߌk?jok?~uRN%z% C_|BJݘJj^hx% ^J'^){T!{)M7dQU DũxUZJL=" _St122Z{v%9[J^]v̏&ğtLto \v{p(foB:Z =}z=Cu2SU ZJ^fi}۽2skQupg wG~pˬQ [x%h^Oٔ"s^ F^T,dM{pw]&_g_Jk+.l(XQFG lgݩ{pRWC#x%a^}X5fٳ_L$YzxIii{Sdw9(S-g<[2pnBJ?j"lWdwQ % ^YyýnS~ ]͔\ĨzѰ9'+^R7-<8mo oJ7SoÊZ-! 6td{`-z%?Aʗx1$5QY57~^xkiqsWjVs@{whx%pz%Y>Oz*NOPo,N͚YoũY罒HJ;pIv󌴈缒),,M4z?H^)NAc8#d2{TYXxeuTg7hH*u;bVmý_ dAMBv'bśx%+O]d+'U֍/4g/]i}\әt~:qP' SHi|zŽ>8lRUnzVCYX89A#j](KᛒJ>okmKɝǖ/59d"&+3揃=ɝJi/>^ W" Ԟ!5+i+6jiOQ.|tYi:^ W" ʿ.5ċtNnDzWo ^[ƙvM- /ބ+w^ xjŵ?5>gK:p'J7D77 k(K-`n|!y<~ʇ{ř5Ɇ|Q^*śx%+xxKBC> o^;yiGxDx%yTMf,w4+ƋtNI!GYW Hśx%+ʺ&ʛvz.EFz56_++;/Jy%8/ބ+wBOVrQ꼒ixI^yW+x&cr|u*/~@CSw4~iOsid26}>I4{u)ν^x%AloB:+_ӧ\ʧjevTY-;!%[)^R6jGl:^[uK:p'n,WnC]a+zDl^ Lgv{5BؒkSUY-7h?Y>~5 ]$ْ+n0RT)/?xM 6lJE 'v"S~W jæF-|xh9:+OOދz2GN}㯩>_oC:χT?*Z 66e3-j5M+GYX=-?yZk4砖λ@0蹯h+_r󟫔_U/7 pwIvW!$[v\il۵[{QQ'ri0jwI:+53CϽZUGHIS/^T%ȼ26%^ɚ_UIXzN~t+O½HAO28Tk8gwI:+YpEvsC#'r|~]{U\tGeKlӟzl+dHtG$+v5PKOދ^k6z%}SbPKoʗT[ $敬K:x;>6߼HC!+w2C/^-_`F ƲTr;u>g#-w?JAyt|+MQvV՚wZ 'tfgf$"7{^ɰM1K‡ ^ p?`e͊ .z.E em=_1}W\_U+fr58 ~jV&$Ko^7+B~w6׮.qW<-yw ~W> yN _> m^Ɇz/~gg_BSX~C/\c_3+r]w/|e _dSU[Gx%Pk˂+OOIgvT@04W_Y&Ѭ{a@,Э8U^),Ns4w>nk-^ Gl+ >SzSuJ C5^|6FވJFh \Kr[o}}*եW܏|qOFDGވ|p J<*R5ESXrf`Y??W2qKkhucӦW]@qW5ESX^ p?5I^ :2`RMapx%o.yzU^ {?H.#(Jy#X4fEm 8{c|i0+`gW܏c^y 8 ׬4FSXB{켕VSz[⭟zx%p`^ig=Vc+~t8IF^7L ^ \kw@" <}ޘGW<-^ۑ+|Wck/*$~^ p?+SU~٘AΧ+"`h9v(J@0@y}.8~x嗿'\$J;֏8OtSoo='OK>P'+WCdJWW>iUY~= <~R\^C3;L'WU*֞jBƻY?=-Б^yzomlW&ռ:@;~RT}^@0jw5˸[W j384;H,x:w.]CWcPKW<-{k(3Kk^Š6y]EW-fJr핋,~A'esn Ѿxj&ᕅýH"IyWꉄ{#MI^ɞӉאY>|7Ыf:[gSW[eϏ+Zꕛ4VMyRɲ85˚xidWOd+_RmR@0M1^~"WNΐIvZz<qW[l^ \NR ^^Q~]mkFje|╬S%`B RG6A\گkOyQ%-qP5˫K'K;?-%ڹWT)DŅfW+ә նp >ڭrkwz"_{O dOPS8ֶ UüR||\OK՛W2 Cѯ+iW>/$ݏ^X+za2nX_VH ygz^/ujW>>( =+S uއW:a\NbJT}f֐@ +SV[Go}eg%acuwzpsRũY8썛w'Vooex!pc#187AIFbwӉfw 썺džxkgЕɸOr>UVf Wx%PKy9E1(fe#x*{GdPQ^ o^yΰfSZ!$$k_>$m]5gϓGbQ,.uF[/# XQCgj+75^d4IQ +/*˿\^ O zub[V* 涿Z{,{WHipwZKx3+WٸAzVf*-+0LꂴDC^*"m21bWߤ%~6j ӱv{%UrJ< ?(i? 6|&dº^ɯOk:K%kUE+Sx`^߫Rn|jWo_u.]@-`[V╆UtLB,'JgpW\\ڸAzGՙ5x%Pο~.HK4o! QUW6zjx%A\˞i$Y:bC{h"f6v(-J*i/ t>5?҅Ƨ+g{rx%p!?UOKoYW?s']z'nIW: r^MNOvmН^= Dٚ,yפ  y%ǪXJGcN BH:)c{'Y+ ^)@'JJt+vOJ~d+w7?7/ j97;oUyT~<ÏgVtzZq6N5uY+󰯉ϟF>O[~:+ w QQ҉$wJ%~+;^:q mԾ27;R>fryw絜oo j{oP啒< 5Rx3+,]{UcY+IWw7rV.N4ԐA9:敆~ן5֥nyNX`J՘ÈȽ쎂/0t-W~k ֽWZY^ Wk̎[W֍JgpWV1>nBY^ }MR?~T;Kd@wzGUq:Kx%pO?Ω.T44 ckiW7{%*Mi+y.Xkw ?Xo~ZxV?αcZCKv>J|qWY+WVZ7W'=+?@$L$里6d^J]&ai: O`8ҷzKvK*b;ͬ٫ƁWgYze%wWui(JgpW-~},yxd?m>Цg c[1aW5ڿ̴IvS1x%P?~љ xK^ 1M;b0c(.JiS./NRkad~^HCI׍!t~`Jm~wsd 7bx%Pۼp^yzp@OR]^1ʄW^䧳WW*q3TҮKӉgpw?JZo>*J6YZJ c*7Xyy6$,AWع^ɯO`oO.DL-Ҽ(CF nm^)^ɞΉ.VFW: =^Og s~\r##+хWSorGF܂U 8$+~ $#I=RuJ^ObخaJ¼nqiy|y ,M"%^)Wdw,D\`iG,рW: zd"6Vʗ3Kknu?^ ^I#yQ.D^ۂ3^ix|z8Kn-`:_},}JR|43ʳ|^>'R!5\КæjqWz:JgWvRi|╬Mq:#8=8m-N=O9uգTB~Ty-q }P\p7ikݜVHiT6n?]F?7EgņW:^]ˁW+[x%hx%U^Fpt@0[Ь+-W+[x%hx%#ZRSdñp+9jWx3+;)J4Jo{YCY~dmwürU'jWuo1g`4zpھLOr! |╛jyTN/s%~@stW?5/4bHLJC_}K{gU'VpY>ڎ,Nd`'^yVtWҎtWDy7>^%yj^9^ x;w )8n҉( a=v9:%R{E&]wDj{t5G1:+RkR5(R `hd^k [ř3Iql5v ^\+d6hވޮL?A*AtWý\k "Hk w3jl5\rU>3|8v߼G9zpoü8@{ur i)!`^ycd@-8WWJ@QڍLg J 7Zp+  }f-+Wxx%!8WWO|CNp~|pWԂ3xx%^ ^ق$+xCvz++J'`^nWW3xx%^ 9g J 7tg J ^^ Wg 8WJ'C/|G?V Zpsxx%!8W WZɌMP @pO.aWO3xx%+U ЕhӏNwJ@-Ntfgx%OegN\=TR;|o+-^U'Jgtfgh Bq7A;'yG?WO+7+Z8o˫7ә IvfPr\ C]=sD*=}TEڑB^qfi'l;@04mW3R- MOE i.'pwYҦS Pl+_R]I7Vc ]V|$JrqjV!-f}vkөb"זM(V Fux9c̎FW `jixzZu)w"Ė?+|x؎ cNڲƺz"JUyW{k50dXŠ-3Kkã-G7Wd@-;ә4BؒӃk =oYR YZSW~N@ytWV=CdPQD*:@P9?:x%PKZ RnC^ ^lbT^Q-3Tߊ :+oդrxtm' Zzx%!;^ w+W!l.߭=+PYxXejjÚv d{WeDvy|iܞ~@{^ VDZ*b5|x%hJVY](+2".8Ztx@0ք6jW"֣+i~pn4Mgxo"$3{~m ^XF͋:;@Kgvgc}x+AtWb0D<ürU'jWĘM(+%q+ٍes)g'4MxŠ6C1JW+v|+bb$36-No}x%OC쎴!$ݣtDG'Yf-wJDIxx%Pru&/zO'p镍hJ+ D[Kx%VW"~9M~Z{jWv@\|W."+G'V4$Úep(J6Fz'tK_ J;Stmgyv^is'X@-ʓq:sВ|-!:=8_\qݕlࠐX]!IiӉl}SyN%ߺ^ F?ΊzpdwӉ&Rw$ YZ*KQ^1-hDMZ[Dݳe*rrg+_lM~xyځ|+9l^ '^ɷo;ъδ蕤{,٢Jr{kزә쮮imop9JUHi:w8 wЊWV?`z|Bl +>ϯ?6?p2ڴWxe:qlu85 9:^i+^=ތ]wã}QZy%ՁpnʼT}?SdӭLwqrI]ZfMC C JRm_(ta;5o JLx%p95Wޫݻm߲^ɲ85ZdwI.]7B5BJx%ÚMJWAˣkYj+JR[bm,څWXJ7^:1 ZE~YWnʒ DV;, =hV|R.eaEcX^ M7dO{2+Baֆ^0tjNʹ+^ r~ov-;앺zIޡxBHbEСMȗg8zE܅^yzp@U~^4}Z_<1fPe D,bg%ڂXUA/Q[2UURrgX<+uaV* 4߼=ꉘIM9n; +DHۅ2{raEҘ#o+N+FܙYZ9 {%d']WZI<61_N Kc^b}]VVWz@0&qv^ 3=[%Ngvݬ^)z"UQٓX㡕dwE^91)l8 ^-ȽR}jKL[K43 Lr|Q^jpTG7W*Hc󼦙x'65+ʼncJn}uWWL%(61Oo_\D]H)94lKļq٣ك5F:W{+cm} wJR]-JAZ6$Zb(b_gl$&vrxi*H^z RtߦLH6+JUOPM(ݧީҫtoIb * ɩGEᕠ}0YXJzcx12 +\^[V 3Kkr`vTHCʔ쏶92 w/Wz_OUey+8T.׮‡O-I4܂Djztl~tlWZ}KևWfԍmh[,٨Mߘݨ586S&M>&8Io8IC^IZ$Kv\͚JÇTP<ìC+ՄdO$tt&䷩kh4`M޽^uνnsWOpVl>½34ye>iTUR|uְ^iV6xeݻ;zVOIfW0IQx{Qy½եhqL'eͰ-7-!_5{&^W^MxW`#nJZPJCi@"wM>&R {a1]u\"nfip(FtcS52,%g4C^Iz$6BW xP,61/^ChSL͊0Q/HZ_*o+^q̚+x+;@07U' pI^W6|.:tYݧ%T[,8Wֽǰɭ 篤] 3Dy8XZD VM[;~R<=-.Q4:@JI8"VQ ō.wdt4׽+SVz;.V||%mHA.l$غW5IEfcK85kxx%nl͆+n oK4v m']bVWrTp4dIl )}CWIv[.wTNW(N"P! }雚=^;=8g ]t5Wcc>>uz[|kXVk>ort&71?dʗ[d(bE]#xX4 a~,W^ JR>4fFbt}%+C^ռ^ :^yе=% w 8ol.\[Hi+o.M'uyT]Ejxd`M.f!WnʬnN4aӬf>7*_qvuzQY<&JsJ&>:-G~8Dέ{6 y|UÇ{q;#onPc8q( 5^D t*uqOů'z?B7:yꎉ|4畼+G+oiz(úH׽$L{.Na=T/)QcV&z%4 JOs?ڞ1+AtgN2=>QW*ʾŻA9 Z[;x%-{B{%eF5j^uWJWN^H5 а/w0JsmvL$@ZGi @^^ +;/JĮ+ρWڛ|ifioܑwHM/h!݁Wz@0U t* +JsF7dl M"4^uZfث.+W!tW*PJ[&J>[Rlb~xtrxt'z7=XWzWNkKտi*JЩޫf½UYr~\8=->P^uW6M^ :‡ 6ؕK_S}fY1|M28Z:Qep(Ε+y^+dQJWnFH_`RYP ekN*yU%6FgT|4JDxׁW`;gZHN- |~}cz|" {/<->lfv_@t9#>%89|DWz@0t^ ݜU*ދfE!.|g4|]:p ᫱{@@+yz"JOW~x% g qgg?vNj*I1i@{o]Y{ur8שO'hpoR#@NmimSk5<f`4FF$yW xWNi}Ю/rzZ3`C-'w+ &j^yͩ+3;`hk g ܽ/)UYN~\oc_oü1WwyQ6 )i)@-8 ҽN+sF,h h'nt]=s{EtmP`5|CN^ byi5x'űIs!nȥ(cWԷol 'OKs'Bsv`7V Y{ȼ8Pp JuL}MՅ[h+R7ƁW5ESX046^ BlW#6eW]4@0oh_^:x%xq!U ^ @NWwW>+nK,ۅ2+dx^Ie=V|* N*G,hox%{%+y^vJ@Ǡ+ Ϲi't ʽ0ã.x%؂G2-h +Gխ|i936*@KTN.$Wm?{TIf}a Nlb~xt\<9dý[[Šg_XѶ ex%x+iQ'c6nvlasp(>5s}.. .ikur9#n0Lgvlߦ3^9X5"4Jz Lr-4\q}.>K_BPo +W&R9CQR')VDM^zTIWR\kydJN`4:+ZzQUO${%ox+ni) FlQK'R\CV%^iX34WGlR+z%Z>,+e*!xZ ^ 4xIr9c8䛪znYJWOdU|It1W:z%?\ښ^ذۅ2M6}ѮHlb~9](/)2sȷm ^ {e[cD lʭ^ ..vdP~W\XD&ևܱ%JwWRV֡;6zO jw$g|4K`gaE[XAxG LJ^\\IyOdIr4+=W W W W W W a^YP s;Ir`IQpi0:8SV~x :TT V\Q% O>IN½v\Qep(FS0 ŲGlK]=@0>U׆,hl_GD*gR88ZLęLΟ<-͜<-><|!FT<-?|Ćճc'ؓ?lgj磟!)7Y~؜6goV>BbF?r@:88jyz>N`cYX hSHq ;OPke2^: @-(7'?7'9>nz@6@K_Tj%*+'Z^7-(w ??GKz@V֓T+"]O?^8VV8ߵtqZDh Jwi|U.Zߩw ?WPK+HXަrQnX\߇^|tFya|c#1oQۅ7YXQZXєwsxtJji#Rg^Ӝs&^rׅ̚xb7='VV|D蕱BJpO˽2{TYX&Xŷ|O@txtraEKr٣xb7ECʧ.cϽބHroji.snjuhtdht$O)~L'U+>"Iqj,߻16dwUtW&3]=ó'"1AH7f"LrŪ}n+x KV76j&Ԓnonܤ[LCD\7{HLw;݊廔.j0ObzVDR7YZ{WYZ3KkMŠ268g_H5W 7NQto#ʧn%`^ssf w-Nͮߴ+ŗN҉$~7W<<%AH>p{iPNrͮ+|x%oaQ2GAZeZmG >H-> 6676*3saKHlZUwcoU->*"yY>O]8u} OәtZɞl Un29_;V=*>YHifզ= )t⾡8$KTHi[ٚ}]TY)׳1ĺ>bQLfB^^/ [Bbt9#VYX%mwG{EV)sYka.ŠfqԽ>(ʙF]Gţ$_^ [X2G!z:MlWԒod+hIj76XzmeDFf2⻆FGtoebn4'OaOg2T>;TBq<%7{H^SũYZ.hsPړ쮮1m;OU$Dbs_Fo.# \|_ll :1@ھ8;IrrǰpP+uj7ڜQۅYcD*GvYbe*˰Q.}GU]6kHl6nOBuǺ--O|dJ¢LFgehM2 WϽΔBOnSKs:ZYnursML֦7]Sg??>؇/~T9\3dVW¡~ =}z[7{+y3 CҊ^:)[w oK2ݓrI9IjVqCzq:ï1 +x4}y<JX5^ɫNXkWO}9Ī>vU~}Y:$:gmfOl[~}~ wsP 38O'OgǃC1Щ%$/MМW>*<K╤r k[؅>Vs* i| &PaEzTxD獘v+ 76Y9^i6J冊[;l9_IW9iM+W+ ^ UrΎ*x.]6WH.-盡~(,+:\w5+mvvHEy?%{+--zGU 2&W+$3:->g/%R91Ύ6N5o Duf*fۧup7C1TJA@/Q]'_q 9lJ÷ZJޤ,z& 7$+DsTI16%/{MlNfZIUG:qj6dP}ɽr}P>յ1,܊=^fuSO֖N׭\Hic#Vx,;цZ!U+54͢u$fIź6r4UNSl J,iC%ʗHou+oKV )&"?,-'wĿ[]^I% ǡ{ie"Ϭ̴a7R:g:D n GBoq%?RC~(Jf[U>~ajvi7i ^UTf@gX#IVFю׵-4ñ^vk68x = oz+GҊFgLɽR'd[r5P+Vs#@=oOH$-ݤ%f6]<]%6ý"@`W $kթ ӺW6VlI/rv Y#zX#s[;<&bk,c#]xpHN 6 MxؚTbkO~LT] c5gU(nbe(nl 廢*JXrhX !a[ &TnxtRL^I"F'JjSX)z0M\Cq,3Kk`I-Why: ulJuWR|3+RXkEMsme.%œ{%ЄW8z,0╴`Ey╴L6!nԬ88V,^݃&h?={+CI?D]FCb5|{? ׯm+uzqs^nx)?ˍ;R%h=W[z?[[zߴމgK|/N|nEv33}\ x)W3sP\nkώ4WV9^ؘVFQzl4p}6/CҼW+8<+qɕY-Wf=taaU`U:nw2%L4FK74xzm^kCGBUט+Cye %W33;;7߭s2Ӌ+VMM+)Wf0!_uiKE7J05}xKinO>;7+%W0^z͕!]Z8pk g(nY2Zvpn oUyrJs啗hv8~8Q}4bRh^Vy׾٥76Z>8Wnno%s*;8Pjyr_~BZzLf.ߚ ܥ/ڼG뷾Zּﾾ׼g7/_?ٓr}s/F`ot7\}=;8Jx{E冤ƟrnirN1$nZ{oJ6eƯ^m'D7wJ[+qr%rRU](OJ]r%=h*RSɕj|J^ 5Q%Wq*ROɕԫ&J5N%W)z4D\ƩJ5>%WPڃ+8\ƧJU{PUr+\ @jjޓ{=vYCMN O\Jמ5 nm՟5ԓ'<~RPSr%~YCMN@Gg 59 O볝yS{PSNguw&?itjrj{w\`pªA'Wf US&?\`@NGTq?/ޭ?t7^ q}/f׿kfgoڣzSk8=U#aT_kM3t:{ ]!rNR 헉r{kˑg&_^>W:Vj٧uwΎR>-z*J R{) endstream endobj 35 0 obj <> /StructParent 100000>> endobj 36 0 obj <> /StructParent 100001>> endobj 37 0 obj <> /StructParent 100002>> endobj 38 0 obj <> stream x]oWuRC@0 Yыp, \'@;ŮVҎ9\hy?l7\|j]c]%!ՏuW_V87>ixm~}u>ߺ_ݫWW7b:gcZKynnWŬ67ɕo|h~|~~v?zߺ7WݫWݺg}|wݎRv&;_OskmWwnmc6!ehf9:{gL\~9g\bx6ht8>i7?~xج|WK?dk>|,;u~ef8f3=cfrsIц2nsl0yH)Aunq%}%Jk*o&Z\lq%.٧+O>NEn)iùX(R+"ȸ7~lW/WWCB24<$XU! 844$!߿bGw BU9(pP0Z½V7skmG2F |$c\ .WuEqhC$4(1HZ%>hjG_ y ZjnA_P}Uy@=K*\paU@PbB(1= 5:J87V8 =0ah3nž#nia:K*  e9kD&tAS.%2F=ǪpEW$Cс<4 ƍCiLN3=i{&- G(S;Ax%ScQ`HH$=n6\yxF,ft_lyGӑ_oapwNyH1\^A~(K*Pݭѣ';_Uʮ] ߄*|/aŎnq[>ybqne`qWބ>eTg* wLI޻sX)}N{1Z樹Q8aVS Z3~pK& wɸĹbnGw^-CcC }ؑw/!d]94#f!ch0;+"cI-zVP/z3LjA|,޻mYuUuZĕ-P?_%9bʥ-FC2e0;3c~] /pmxEkb`0MtQKDNxTYj1}XcE_T9\G~iFg7N3piQط7Kˢl2"?pAe? 6C ^P:JeX9)Mc=日+nҧ\f}{Ô<;,#i$ (p̣3 ?S{ɰV% :OE;êvGz<|ȒKaܢBLW'f(%Y(G0ҪIZ=;IU4%SЋ,kL)O45K;2 'L݊~ EE/b9dX>I% ƭ&C#˿-fRҴADTzݣie75{#{\$ !|D)UX,^F[W/͊+z܄zNq4ѐTdMg4cAmîNXWIì)m 'M1by%VPn~kX5&[%4F=vjϏGGeΌr{d瞞>O <}=U]kEP`_)d X^lz{G̓j`ZuQ"29=H.#d "oKü8*4~CcQW4!EaaF.7SЙ]O[=eڃ迲Ddn.: T>T@%b} rRC&]jSijIz/5]okYa٣!aG ~@NBp Hhf1%2/Uj΂޾fZq' g^<$!("JNg'KCX 1x)aWR:JtAn79 Ua(N?10`]N[DCV|d{ 3,_U~v.D";6 [r}5zvs)%YV󑵊d RgXaŚi˺Si o'9+sC~-Yn-se ItSq!l]"e^Udh ce'z:U$8Oy id:-\7z/0j\A SԛY+4 cp5KB7)s4=E˔zfy j.Jj 6e HT,J yxg`MN^7>5l=,[&]xk9&&]clJ!lsUJr!! p1 h0UoV)D([9J7tҧzpgnM8ww/+[lc 9v_?~ >|ړm~]sf:1>YL !H},7{ꣂK(X \C>|܁ n*v,T`ͥe y׶-"i5}֕Kt.:O_WWJ-}.mw~.ie_otYPEf)qOo߶Mb,& +d#{[|c0yNpw3?䆃2 endstream endobj 40 0 obj <> stream x]S驏dIT]]ed'(J@ (b1$Rߏ|u{B@DDL2dNb'=3}o{ÇG{َGѮQJbq|iÇJ{A1dB^@AV誄Lԇ^gdE myyiqiqr彪S)ܾ^>| .YY7bIzFq&[w͏hdfXgnt_@|hF1*ũs-hS/d2_Tt+1Q,>|2LS IKtʈؔ)$4n_5`DbĖeF [!stQfPlKv(.x婢22!LWܾ@>@%w FAacdctFߩP:WUD(B6y*F ЪӰ$joVz7[~1EyUc*f"QJ؊L#< 8Ȏ PQ zn.[ҘP)stLBCNUNb誈Leݾpo!/ _Z _7i^G_촄U0YN׋ʈFg0A2i((K/Skb6tSs֧;g98Ɩ2 2x6[ Kںr;4ob;:7D Y/콻6BP:,'WG6 x77k~~&WǟZ\[4ܽ Syi 4P"ں| qsx! P{{]Ue59c%-4dPb1&0{6P(.ـa"(-L3'FtJȒ%"ѐv_C\wS8Pi[ov(fN!LXWcypBα@D/m 120a iȞtDDT } "/ U ;q|Qhx~VTW/N"4 ЀPepraNG|@Ĉ# x hHbjCq(tBkƞm`N\ۏ*;Y$F͖XFDN_C~PCQt(4b3F _&s6C18q{z7CBC1HȈViĈb(i*/U](T¼E5[09zHr2??ݩu-$F&s e'1KGLe^{׿E`Vn_EyAQ(7^8eBqq@/*߫GPbzj$@ra7KDVSUšPqO4TZ3YdZCF;  AXaʘVu&F"Mq4Dv #qӏe@umoBۯU(f4 [֙qP͖T1T9WEzydb$6 &Nz#Ӽ,R>DDY |n_`Q. mEf)E5>0 'A7#wi XUfOzÄx=駾־Q@=?1hҽ [/P^"3SX BB{E D GӐ>mD%YPT޷DZGG&FTT+\mPHI`f/ Q:m|E^. aD#5UgaIM_PONk*a};G?G{lwPbD$1mH`&ܓU0U;%',!E(҂+ = ֌'Ywjf *Rt{wCC\_[Nb}hU&MQ;idCl/(:7|jgBkF}jK%Tվ 7W $U^$S+QfS%F VB|!- B,X?E kn(s1L-lkzRN"yTo[{/*F ;V@N>|:vМ;+!DLCĻ2?+ u[\|:wuP23iss+з*xHhLB5$ċd$d)^S $ra* JrWUYUvnyr -9~PCUmUggѴ;!<|u/,'FJvBltHȌ?xVIWמr_" [hGl* |CHi7CC{ֆQ3./JWxsҭfޥ{~(TAf{/ /V 3#oB]!0`WGH=ʜ>%＄}f%&{bn HW@*%$WD='y(ԛSYTBϸwr_%l&םͫ]cϠÁ3(ӱ uk7Mn?d!Æ}ׯH{=pdzKT>  u:q}}Å`8 ] I*&t U07z,}@tPk^ [I jfn'>p7F,bx=Ԁ|iϲY3- 2k[ <׫} /-=z Eu9ZVt$\3Ⱦ|jO\:5{nͫO>D,aS#ԛ@7P7!6UBE't+NVg>e{SڡTUCXx"<9lHP Zެ0f^MBQE_IȄm¼SV,';: }s¾'Jx<6Tt*?~+@`PL 26GW%0^,S[=M &mޯ8A֙Q|^!ڨh/ۮ_0Pn8`Ϳ7Bó3& `0Wk>l$&{3/7T 8 V`)oX@< a`>I }o?kjlV; F{l^.|>/`wv;6򍵶CwfJW_lV@|sQor2~Wx[CO [1|4 [!TUufQ ==]cϮyjR$PԟTa^|P""'G4't'10`Mx.(`n\α5IgWT0\d>.E:G7ۇM2uE.eLt>>0G^#crWϺWK`Ъ/ȃaLoum^Z=0$JvDPZԳ{AegwR1[8][Ë_~A'b~kF&_gOKo^.K#@:"b0O'Y9X!#*ٗZ JW^D/*ӕ[7=\T:.bȱ&XAHZ[o*~ P/0 6y"'"TlzvGM"k:R9{זuK4LX8Tp0% @KD)ܨ_\ds=['Rzou Rbװkx1l̜+5Բ-I5j@b&nh,K.z>|#CJm<8  (9(}C@Jc-bEP7.Ab5P3`Όh:!Lh49%.Gc$c ҅bGjC%LN>p&A:on#biudxI@:F6TB(-wʻg2T Ys>}d>N<~?vxqwpU> 4 Ψ Qk:#t땛 Qp^c+Q!lzs2Tq!e40n$k;xj+6jjBko0<8& ) L5lSA"!B=BI`Xa7ka f;ƚ'qe-aONo.S/ƞ]?G`'"˩s nF4,QQeFx*`@#ƾq] q sH:\gStsՕu Հ) ޛ )B<#zjr9ht9:Gؠ=8iiEj.ƶcH䲪[ݷ%]kh5Lh ox^߻~_Hc4D4SfPq=# Y\V{Tg:R3QlLa᫄@*w-ɴ5bkӰbL=9;k~T  `"n#ܗ 8 gv d(p46luxRm02)r_E/(M2<7;qݾWBH o`i+E^tóC4B`>ڗW +0*PM6?^F1Į#K ޣ&7)tΡm3NǶޜ"?%q>ҨOgzr΀iޜj gƮ?GTp7ϚAF7$ GZz?h.侀Κ$# lP#Yә-!ww?Eےֹ^2\y&X=Hc~&`SA+drxqwc$a4rC0$dp&Cgm L8F@5&]R#]'PGBbS7 9!#ь|&#]w [6jw~mULۉ'\_^MԉMW (Q0%jfG[FVۏ\r*v?9?3]=L<~-|Z^D[bP#Rv2Dd:3"J!W!pWj΅SڽW\=i}EA_4 vd ki3~cܻ^_ ?{S[2W!8T`)ςKle#OWF6d~o~p(؉3s;~#~@\GG4?j _Z}lH`oZNv0;C 'Wޟ0ع`Fqo6e#T!Q^5P|P포(䌍?'@ZWt3//槙ɕcލ.^zpUvޜQ/( oyy2ԃ\鑿˥G:{g{S/ϻ6l3~qhm3\T-p:"}&aGv6X@Q8?3*`-^w#~cz :6Z ;D<ПOو$QzԺKAF䥳f*h[g@ @*%<7p8mq2fƤ8}[|}ޫ-fc}O6y-v-/.󎆰gu2 "6"xQVЩbvKq-P_ &P !K8p11E- ꡙRG- TIC(ys h!Jˏ|(-c٤32p D=f#L[Ƥ_AXw{m|hv?u endstream endobj 41 0 obj <> stream xpg7 $P:-MEN4A1N;=Zu4XMB Z 8IvJf bӌq(bc$ml\g8r{w?gwI{dyy]y2jdq[c_DQQArZ&3=O2 ~LZC0jE>fhύI5\@Hy y\ ."ޛ!; mFyF⤸{{}R4j-ڳY@U_.jXB[6?f'w`:@ŧoi[?0qmL<ұDw):LXM+{l`&ZEf*7+s[l0Pl6P f$]~u3eqȡV':3m=ހ1qP_+r2"~n_ujf(q,zzq]f!Ԯ{ {1\vSsCFݽ7y>9Zܦ0PC4tq@p}'9o,%6# TAϪw^g֎,3ƂMW8' h=n6?7` >vOo4cՍ5K1 ԗ0gUu>G!@0YD,ė lí }jBBDpFwrhC]|Zy`Ae d&Sq`]`.ubQ(iE* +@inVֿhU<.,!#岗8/#*-k]ìB@]҃k#*&RَC\)Kc*`V&)jr['`]Vy2!#`iXyi7# TsBY# QKKf(lT JLWZIs`& PmD-/h60KLQRҤVnz =CI`\73 4JlLPz$iR? cEﬖ 0J'e '0GlJFb5i0v%_|<0VCnA"IbIF&C%sV L5Kv I&x,JZPG |aE'.Q"Dcu#BtH4pP㪘NTгV㉏R-Z6}}ixc;#F} 6YN|mDeLy9_58-RCmbihk 2 t@bq&>!yCbQύ 8𰎛 2pEv^24"@<4h(^*{lR]c, e> d;TK|\_.5D9/m#_&ySC-8+KdAm$~L=*0yzTfC52J]H| lpg@/Hc>?_ⱝYcEuMQ48+$DڡC΋Sj3 wښ[U^Vr1) >w 'P;Q< ųX1 K@o024 40tGaCP)#hENje^34~u<[˘W4#'@}Rѫk?Er ى(T-8JP_@>36.>8>'3c)݊(3 \K)`ੜO3P΃݄'2 Eӝ7$ѴC4kx$ - T6az݃jWXp|>&0/a(;EטUnUq3FP>f~ϴQLuT8>SZɓxҙqaN Ɲ|+U buMQNbֵoك ;08kȯ>fWzL9~mx7pk@)u R_+tyu OgZ{I +Q/ՁrzAbВde[;,mS瓑gѢ&f3ae>5Vf,:0/#y}`&s4Mӌ Avl8Zȳu ,E$E|LQ}'ڏ4ﯫ] Gi jeO{A'/>!v҇wwjk<뫜W,)+QbdžzOw|`׳[=֮XR6ӧ49h endstream endobj 42 0 obj <> stream xO]?+ADMH }iRXRw"JT`|Pl͙3$+(!9{m\`% pI@i#BfI0:+_t-.^D4Kt'-5B:Yh}$;8ti=ღ@jl_Cȉg.5%|~H:JPk"(T}0vo ݓ-C(;l;\}&c.S'SBtEtdfN=Kɋ3C&Y(,U<1aAiPxnn-OHЧJ#!L/_st g2f!(V~J΄?7XBN2d}v&c:3U!t`u$x|oΗg2fСҧ(zC!^ C  C{/ゟz=thcHGzx*m7c*d Vf*-{Wi$Gs9R':L4XMr&c:jmؿU!th1Xm`U`UVU.0XC V@wb0:;NÛfg VUCU|9"*>t&Sao;d*> ñ$UOG UC V2XՅ;N^oTjc2XՔ:4ݓ VWW V{ VAjS_'|`Uwv^=mt1X:dIu`ջt&b V2XvXr&.2XWuh V)~:  1X5o'[S (ÛUdCFt0X-uh V.t`UIw8z6?2J~NC VaF7 Ot*jdKS`t&jV VQz:$:Fj*b÷;=D !UH`5`2!U!U8r Vu`NCpo V92XBF V!Ph8 endstream endobj 43 0 obj <> stream x]S"K~:UO`vͻ&DFdfg@PPT W >kFASҦN"Lp&f b`!1FC묰M$@8 ` H2TZH0hA,F4Q0 5K:[ PFU`$$-:&H" v`e@ 2@OjByQ׷?vbe1s2|ݳ΢v{S+RIǵV*?Az dl߆&~ YƷvܾ]J11s,>|PתP 3Ą?97K.>e0$=*g#[lqJy4]ݩ]/=4wv]ܯ@݇_VFG·^/at|x)1^}@m 3~s`W N(սeȫrwa/萆H,܉~f߷Llqc,^&l0cةwԻ=lƎFW{B-=!w~Y\>2ygw{+>P>nYƓxgg6ɓ|QrrCfvݳ>G 4o\] ]%mT]ov#'?{3ism7>+yX"[66­Kݡ_9˕<_'7y &]uV8Hg1]^/ T~ֹ] -6~GvY1E6_ 7Ejj;/$mg}/sVA5wKO?~|8|^YjeMD/yt{/; v?7~\B l_;m"_Qdr'W.kꪜosǾw 1~7 wsI]>_ .4uKFK EQp\1E+-cHdZ[BIqXYۻqo㊔:ss!E5!(HB>)]MV`Eg[R}U..TҊX7wVp#[xFuz:W&>pwvq?]XTQsccP¹ONid֋ktHt%G("rղ(U$WΛ -ϲ"nFͪ*?|^iwGm,#2]F$q.zw[DG(c&5~^Rk]GEYXkQ;SW7si6KMl5c4-׻?vu {5>]K_ù oB,*ziz ꍋr4(FG<]q&+zsa1u0r2d%jב[a_鲔{gJ7.#I8C-2rܾBGsCRea_xew W ȗ hc6g򑒛I:rގo,]F(*+6¡ r|S80 hY;<5t?/)=ZRPt?G"C\MLv@$qI5A.t 4e ČZ T\@J}j[VG#It{Si5wpG]'cCfwv9N2:+\r~9`+}孂{49$jy&o9GV9~#5M,N FYZ-'~j9U^PCoHQ\N*h=8BGq<#Z 6Ž=-xTQ\E6A1^Tbh)Wu廉(v1_c#YxoTAOnU>!Sk1#+;F~=!#4R(*Zω-짫?y\>ZUvdCĪeqzNouTe?H -|!yR at*d[0O*k("mY0J`ƫk9FE vU@6y,>"뭰JkM=sD.F`ɅςoŨHܦTdz+9Zϴ*V9e9AHnrT2mj/?i8 m[_}06hZ~<߭X{(n I|4;Ckʜ固:+T= 6#:뭢QbL0JBDHfhܵ>w%M,+X D'-=UMQjz B1\e>X-B/Zs~^]y 4J1v72UrFEӛ&+$YP.yQ\ܳ>*&ǂ&g_V>}@ͷ<&5~U plN+pMdnSS;]A 6U8kqJn Jwv|C쿩uBvWL66@n7Q\ ;fyÿz$ MZU%U=d&cwvp6#8)CVŝ79;|{xmt[ӗdVQQ1S+?F*Mdn.r: W- Hea25VQYPv]kkX gNWC۾tP)yTǢRI'$x2eGHRRc 7wϙih {%EQ3gyx5-ۓP*r:({7S%e$3cn`n?+˴ąR,fspY!Iݸmlտ3Cc# ~9?nsL,>vkal~ Ǝ)L!6;C֙S{PrMdb͔uwxvai.w:_MrEL,15rM2v9~yh9I${1_\8+ŏ}vSjTb>3r fO:ZƷf6t sy8pڳ9HCJ.$+,,i^ck֙ݶ>֊CH xg E۽VX:L|6:$ ʊ_k}Ocgc7Y]~r>>o DF75A_/hzSϱcduCCj*c8-/6;C?]['1.i1XNض8г{,ggg9%?PƐ|b+bn ^Rȵ5>46Edzf4CcH0F!I{(2P3}4A6:$%hl ,kdQm\Y:mfeMR}_4{Mh[D5}APmvp"K" Bc3҂רO8HJ: R31p×Q Ҋ i@Bh\ak|q3$tj!FPAXͤ&`tPGfln[ 5F'9$2y=41[8Kp3|JRBsKeF?Y^ .@QJ%Q+G"88% W˟_Mk |J?]15Ck-(w]|C"謠+jp8-`OI_=B-謏4bş\a`aM8K;_(`i tݐpNtX8P!}OǃɍKKLh|F54F$NnWT5jg@MzC--\8̔@[㷡(FC TiQ;PG0Pcpl`AcolZ%m˟VcjT~Yit0|c-kEn7FzU1kO&A J&z80rGsi.,֨RJA8i~40RJ66 tF씫SHc9rHQ%ߨ٫4z.,=xD*Q@@=.$Sy[_L^p>SBCrFuS(ެSHȔ``z dH`z zU C#?-iq@?M6_qXSN#G'iI IDO7 +eU 0M]cC1NR5+8B) O98C'Ļ$wv"C#0ꙓK)c &7nn/+_&+lǖh 4Vcq|fvնFE`z4цJړ,E)jխ (`@]?}n`S[T $$!e{>bR]fF)= M$Y5{{)Y/^V/+SNs{8l1Z$`4 ZʡskKAωk.uT-YrkG֙־ZĊj{PGH-ј, E KPj#6Y#Pk Ծ;Ƕ{'7ˣ*gCv:up&bPAGB9HZW6AQGz[(;r.}vo[gw{W׏^ldQZ_()9>3q{'k¶h*~%RhQ(՞ S"Nn¥ (?T 0?"2E+, H FJ@8Z&Y]k((AMTJV^Y endstream endobj 44 0 obj <> stream xݝoTEҊT9r遈"xTFLzl(ϬB2A2*rsv\E Y"g*4['"l;tg {=64!ejAy2g駱s?`? F}jZisA[gq P#Ț&{jӞ_$XasU9=#ul~kQ+S !u4mQ3#lF7њ@ɦܙ6:4QQyiHG5s?k?nG6O2l 5fg6WOpgCHo`6bF.m|gfk8ٍ6g5P٤5jS-R:Uj)4 :Հ !~'YG [cPA费'B^_nezljܚ_Cg rD{ɱu/ilcՉ6Pf858noC=B 9 )_MϢSc#g̝A=L]Qqp 6 pUf$!Dfڴ:kD*oQLcӕ@&yitVqXobySSt&HʁStے'{Ћʈy|A(&1ts;fVtYQ}prE`3ZZ>KyA3>%su0#H!03EWC1C7֡::Ruo:VEuny.::"#O38Jd_­dV[]āH)>-<}: Z!aТUG6A4 &Z#QlV-F-#ΟrW"/*┓Nj\I{Rt8:0i*jR:NgCt6\m֋XW+/dx eHJl0Kxփ[ b1dCy =]mS9冞ײxH: %grm >5=6Sn:7)VХBoV&Y&a6q_Z+:4bq~7v=uAwl =c"nGSθ @ |3:0>ΦljtE|r`)g>eW\OuOr#^-s=)\/P-:bC1G=60Ԧ ;68C`l,f&htd0_Akq~!*T:!;["C,QöRonϝ'lI ae]l _@֯85ŶȨP6 &2lbRSY2 lMs7лE!o`ZԋlDǻorbZiɫ޵a$)<Ҿ[/d=??j]i㲩j!$~x,NU 5.ߑ5%:4M;$}O(b6EW?n\ihzCͭ:1uݗ{7JX!$sgR endstream endobj 45 0 obj <> /StructParent 100003>> endobj 46 0 obj <> stream x][oܶ~ׯspx e>@k87 Ż8ZIb#rHp-eQ{٪KӖXbNѫ/?͗5Yuwߐj{w?>6Vl?ׇO?^)/.WdEƇ>ykn@9Q?uq,gg7w_퇿ri:WbYu{Ck t9*}sfqOAWQ{yc܅1.AO7.%r}{L!vP<޼PsC< Pp|6a&9<`ec+PEC6a8Zu"w1lPaS㴟4>{I2_H`w1K +gI|t*sBFYkx1@ 7ՁE۠Hk5F/9* rj0)!3zPxكC,^`bx'{E} .8Lw@)_Tv+[[;H!G(c,4BW|u6%G(9١=6U4voN!H`^:4GI&\`GX'ŁpTM) _ql2z~'Q,LEL!2BEزKXrtƴڮ\Qi"g>J)+ @D:ef*0rgL,m \(Yp^-AF|AV܋V^ya>5gS.䡜+?,1lIE*aSpj&.HP+]s"c zԒF!armeG8P~A1lJ],!t. 6+f 6CbWE_u=܊Vʥp Mj2dm]7ۼ!rH6F mLm kdYS) :AF+@I|5E4s&jq" yܡn^lv,s&2|Ha54kg6Q3Pxõq r zQE8&5!ˊXEe4qX0q#NYa F-'ToU&QT7% !{`b Ɠ>4V.§d~'!XbmǎC"|J|x,ETDoM߫|Z{g'44q ˌ[5N#̫edH/^MM~3^$|Br!pWT,Ar$xeJ ::YeoѶHu djFY7Üp`IUߊmߓƮ|7:ژvp[ M1;)h8.bw0l¦2qwaV#q9R|LE6Fɠ 66j6;S&GMpeXь_50GlK,ݭk`nAo6D0,JhD&`h} fiīd0)lE5݉bUƲM ʷy}69n} yymHCk[ U* p!8j[pnǤs)Ls&ÿ<4eKOa}c/+f?/!/yr嶢JfOCL6&`)ȴSU4GOp9iD7DP%0J ]%g¤vdKo04hT;Ŧ M^Ow2TJh. DD3XT=d r[6:\E8{MkE۠ ad4[czSnMQnoιS[ĤrӸ%KzgcjS758oSTq( ("y;WuZ(Unڄ&> stream x}YoY^nLu1ƞcy~a~ vɌ5HQRIbqɸq#27qČ7r&.Z(.R22"2^P-1;|C 4VxY! "" b+_ŢB#'뜬 ?*1+k^Y+o.@C佷Uvs1(U뾐&uyS_Y4|AS #$|Q"F /@4832fԤ?ŧṏ5o9 ,oqr:+i/5:4}2b% hL@ 0Ms8dDjq_$Ȩ5o+8߳rhh#f!yMGDdd?zapf[RT1_%1 ŪKd+ԫY2-KUt`xmyddtO-ͅ,~H;}rH.Q:O鯗fΜ3.lڹ"_ NCTҮiD[g(ILNnܳ5 yloph!y)sl$%}T^M]Pŗ}2v<\2S$$ټ,Vb+qn]; 1!*uz<0EI]CⱚD/9YzD8pb^,@,.a y#N )TɣKBwnO%K*hʧK!XJԡb+F|^phNWmTʛ<H@.Gy4lvs'I;h0S$1yWyuVt{^F~I`GD=y5 kIhʆG T=ҋ;p2buD(ۏ+m g~dbݦ_ & 4e,fh] BKm0~.% Y3iKg㲓޹12;_<댤ӣ}AX:Ut%9RN lj3itWP?fӒfB >X_LSȊCGכ> +a 4=-i1Hz{_n/s>~-( `~+i"D}%ȎʐC\վj/AOU q1u40M۫/p>~vwS$Q&:hzӰo]adk!cGI{<&wo|tO+D{!y. 0nGu|k\ëofM[gH̚Q7) ѫɤfn|8^lO* nc01r|ݭ+W~B2wD7 Dݐ*W E⩨5+Ddh]*Su[> k+ܿ+aV"]Q2'qQ-W Ѧ*XP~6z><4/6E^xwpJ?1ub_P~,X".*~пeq2NNErLm+ ccEхrA6 TDsv`-g37s/ w[xy6ܱp=X{V7{ 8J@"[6ʮi ,nCD}WPpondmgZu&\?8H]/+CFheez?g: Det6N!!*~ ~`ے 6=2׻awvS 8G/*ԛ=ߺݑY>~<<}X2z4kڒI.X,ļL7 ,WvH 1ݐ(7˛bՉ}Q%+G >n&b'U uEUwF[R>ʡbɨ f-Up_;_)'`ւ=MT0xe`ub/.ί㌄nM o[n<ߣݻxX4:O޿UV̇{7瞋*&%ןgV%glO@|P<[`8{e"_(X~++]/J[~G}yUK'cײL>ٖO4ehIV?t0/#VҮZveZTczoCȧ#4Z@HVW%]?%@Tݜh>iMȍ/ͳխ|X׎HAn!}Tϝ\ddE(E+Wvy(iI ^}uYM[{Yg^hME30 L*'^z%*s'6\e]ܼٖbbmmW U/wɣޅխIE0',ו!{.Bn|ټ߿L3$Ǹ.7Mq ɺ4R p!y.@Tc$Yq2-I)(%mrAfXND;:wds8{Dj C;"D*wM`x"6"BEHkŏ};!.oy^,8"`uv0 x<&p4lfViK mrljΠm=ʾp!y~=v@}i`u&fi0'ȸ1⎚ m(.$9eք)r  M>i^3ryCs=pY>9 ODԼY7*•5o'3emXi:[ɰ̃eZ'z.ȦB8#A׼j&B,()'"'Wy8YoYr1u.(dy.+\F7{ Ş-(}'&4=^dnfQ$N\ٳ-H* kx?iuk{ CaxȧbNA8tVwG ZT0cn>\mn\#kǵ]{²+zc2/O;C(/PʌL^= Z&m ᎴKf@90emtonL+[MWnVd^g9T6C~$Q>ՠsO5H2JBҹ9Jg8wW-/@9$mo/]Kovg?zW`9qk~h?Ξє#밉0\Ю` ӦgI hIh?eV&g_o/fe(m13KπC 498~"@ĒHtM$K;RրK30eҨd_LYGA,w?07᧖nq#Չ=P[l0Cow.(<{5 42+npfz!>M8lo.+׼loY~ AV+O~/]׳r]TE_(w94~~ɟ'nsrEPi.%kjO~%+ZpϚwt>|:v?ߪ/ڱO5>077tײW@L\`x4/7g%/HOd-~ ſm1wY(J]0gW3:Ks- C]Ŗ\t8Kzsg+11hMdcִ&{EoEG:cm ~_rhā{xVIxnJA,G*dFIݙꇪx;_S͊T 읜UCc^!pZO$„VRvEñ.єZ%H`rA:U@1$u7S+2բ{Mŝ!&:+R޻lx9ñoEe|8-ี>BsظW>.6ĸ^5"N#}z=Wp>qSJ-P W~I}pXǧGԙؗg&ӊЇlrIkZ\>Q.IRZ΍GD?vI+|xM[o8R~qU.i'2nc~`3:>B. "NA"Dt}):l)gAv{>Kozv/W~"֯ߗľkZ 8 ^ nh ;,o"7IF~ F8\}w:Nlwgh/hH#Oټ=GGkڒ碂Rex6Y{R٬No(#ĭEܧbAAā0p⻛Wp3-kfÅQ_opd'&ESt" {Įxs1u>YWg񛊠Y43X<͡L:%h,J+|ACXi&y Yf[:8w;5N~4Ȋ-"m/$k'f-T?M%ǥG$-g<%K8m!H180%]#oF^f}~vWɚԤv7ӵIDn~ bҮ0B'}.ka(8 G9 մe{V^xIqiIm AvPZ)ڽ¹lWX6u/7Sڱ`46](oD"DIJ$pA"%]zهntcJ<WN+ XdݧyG/[tsQe3Iu x V :U6{CT vnu ޕ7-uοO1* ~Dػx2$3Ёͯ9sM^n'E5tϭway'RmDIěm)Nkd7!Hq}O's` ,qz:}b䝕Oݻ~펷P[=x>KZVIvB8?裕rhHPpF-n)!mvgqz:}xL^F9)"ݽT$3>\ uoLuD9tQtyWk_1tS:?Gy"Y͕<{+9ʺxпe͟+C|F)ŧ*74Ad0/U/`m3P\Pieͫ,{"m5~.֚ ū[׶;< F2pGOh~&SCL'uWV"edl+Y;eG8l<W[=+ٳ2ϭ_:2*fAi OzɘJ}Qm%T0x+[POy$!BRҞ B\!|e87v-:6rtphȧ`,p(o#s|?'^\H[b +v`ԯgVT5'>Ӥ6\dw$u T<˽f=? +3 M澞,0#*Dƚc|6^Ơn h"E|LT1Cc[n}"AAyq#Jٵp"s|A@ĹӇ=2ۨWqJ? . VvbFVdM Fmڶ~`PtyW5v)]?4e2nOYxW1ZN/FH ʹ=8:nMPge6˥@Ңj;%>}߻կ{7(SR3Z<՞l;9_]KNZ@S +Va^ `A\kХ>UwB|xLRšE\s+No5Z2ij}"SA! ]߽0pvG4WwE^ v߸F.7x<&㖨#K(#MlO*j.~AUF = W=6f[r!V{& | GK.<#Q)B6ťCTc<@Kˣlmkʺhm4є^qU-ȚCu-_ yt&b'"D|xU!c26P|z )H֋90D"7ڒ%$>\MW|"Դ&@8{l~v5YuZ< `,b|uh@LPPS絝ib'2nKi o.Fxd:$zAѬYwc{;W2j_]_@u,ëߦR׿%17Y}Av$M(:ؓcbNƃ",[.k ŸN `dBQ#kE(Mmr ]|Ax@ 72];&$Fչn%򺠢BuͿ}65v/w:ӳR&`qGIPTp>cPb~`I2zqiI LYsd^Q -h54:]xt`iA Ă{ʍglj;i2y8e%]ֶDhM$q- JҚsϪ)kB߾a4^&=K>lOw$gcp V6.Zte K "mȹݮ Q|SE(AUx'VuͿ({Q4/ˁ/jIc [ 5Z ok ✼EMl<:Gfyy׽ ׉>9 bF T m>ԆZᛄӻ{ vؽlJcכmln~&B6!!K+L8d2D8㖣=v\B' b^qV묠1쎁9y/CR WT:'묬 9̿ٵdU~aAM16Mqrt!)i|ixGx1*qvBנ}":#~h˯*q ,7n'Lz)9kz7u[խ΅Μj]v=].Bap[RjʛJ.I ؀&(V{ʙs@=_UCT0 K%Tv`$ۨ{#꼂CS6cQŌ ,7ns ,NZ{/+ :v|;]۵f۲ٱkvG )%!@ bR؀a!r}[佋/։qv0syt6 uZiy}&0#@$*H#Cs2f!&Y#c`խ=]_ɻ͎'7?to zL4e='7 `4u=gHPK`dhb.#S{syHOw|*{^ w{6+Cqe|^LY&sԫDHl\f$ }[W78qEmgZد`ȵK4krt)FhR'`tWT_5X,PceMP5 P'b;H}ִ%Yg(;h~jK!j`j$JC\YKWѰYp C?toL?+_4u>zLlO2q&"&z r؈27 lI|QD‰N_p+3M-EKٚ8C5Ŋ`-[*^ w?/.ݹYUy}Vn`NFZ ӵzt0zO78^xIoD%A]/vQ,48DE tmH#χV."1^,j~0}3Cs`_Hb,1nBS/'b_ c'ݏ_{7+CGmpD 9&X#bՁ9QXUFU-q0۳r|b|R;,jy2ld+AYD-6H Xzd:#W@~-vxwp"v:?dq, lhMt r4Gf=ߵ@6ʚ5ueڈ/hW$^4[7ۓ;7ZUxE[H."DDE+J@y--UK[.#_70HN+Cݮ}[ `l70S?c杮I% )0@b=T-o{Zbˈm0UdzsIk͸ .(Y NR,± hjPc$2VDT042FYHjVDxrRL쨬`y'dNbq7Cn0%hXI33$> stream xytT$a1,hJ,Y`pC)(n@ OQ ".VYd)TX Zа)d!ۼ̛y3!!!o2v~䯁}wƘ}n4:ոjgV|VݹsZhUWs=bTsl_uh: zt9w:mVhc3-fb鷬Bvm&vde(~NSwE]+^9ڥ,yCt%I?]+p9r$i:6.ހκ*'4clGRs>J5O탮/9,QPJunGRj0=Z`rKDS&;69"r/FP@?IÈhyH%DV&>fM"ӇNpV?}'97Gu4&sdiѯ/oIw!qqd47)H2yYGXa% d;gb1wu4kdMe5=@ 8Q#x"}Ybt!WV>u\G6F iE6A`#|td[rh'"<à~li=-pJ(9@nzL=% v, ~);{ eIށG4?e(u16W"cs_z$ɻjmE&EтjOCl>.cOȪ FΡ%l&mȊk{kKDm`W;jYZgZ44*TNC^&6 ՑDThR/_(>x,[ ã8Ms0~7|JJ}Pf $Bi ,E$_6 ͑^N}poGھbd8K !R*Mej=cvpY/ɑ#O.%&b(2QdE=`ŻI $`'o*kD Jւ+fJF_f}D #cc7J #cxB&u7dLN!qٲ [v2f Q1Ž-$a[K8kdG "~Vz}pR-%[  ]Jjw!WE-E3`߄]s_0B``]l`9EMp\Q߭ 7 ű&v 9fƐEKBq"B-C6܊DȾ qT (&I[)?2E%r=d^wR5p}* ı;Q 8~*9W?b"IO] i$C3~8 Uӳ;}IVAք8ʱ;&rs+R5=&F+>ǙD3p/&JܐR ?G ¹}x-eWa8U'wo] ®n5|>*ܫqO8'Jqr9Z/ W3:3ruհ{yz:E|0庰/#S#[A[!O*hY8ե])S:zZgfw_p}׌#Q>I})qU[15+:NShV4+lJ#TP+=d:{GґBv"d8>)I+@#uta/+"Y)It’CN\I_&sC[#ߊI]ְ#dk%áȞ%7.C?s+-\ *8 S`㸵bud_vN!5lܒl#~JM½~};y #_hqф侅 qY\u巜a49HG\'G)>bK&^J AЬ43()6弘r67%PNpʎ+Y]~kW"3(xS jVuT]5BhOKBw1(]fRHO5 c-e SNCdv 鄼9&29}:>WSn bIDX7vѻ ˭LjY 0㽸TK]U/jOrē:lqR>cY ,14VnOIk*$߹Q-Pjݢ6(9}?fھu$\թg7d\AFe;qF嚺Z)Qĉ'N8qĉ'N8qĉ"5v,NtyhkD7f>< 4|Gޞn9;*\XR"}Hr k ` c Yl1솗77n\3.O'? ;?tj1rN/kKpe=r/4>Nj;_pbX)|;vʺ]9pCRe5p> -aR e=r+NǸJ1HLl8'Mx U)~t2o=QbYq* endstream endobj 51 0 obj <> /StructParent 100004>> endobj 52 0 obj <> /StructParent 100005>> endobj 53 0 obj <> /StructParent 100006>> endobj 54 0 obj <> /StructParent 100007>> endobj 55 0 obj <> /StructParent 100008>> endobj 56 0 obj <> /StructParent 100009>> endobj 57 0 obj <> /StructParent 100010>> endobj 58 0 obj <> stream x]mo7>b>8 CHcZ&)p?0k{ƻόnZ腒(|H*iOK-P?d/MG1Q&ykCҰƭ}çFݿ?m?|\_տ׿?|k~|ۖWnn߬ڷzy׼wo(nlqum?m<|}}÷}k WWm7ȫ{j>5tVޤК>|jȾjÿk"^2(G.d"Vado1a*XM<1}iaj|#8e'3COc|q$O$~mau궾mbVt1.G^~Dش$)i_v]*mvdY926'f{h9*mhS+w_? N2OҼ lB?ˆ׈`!!}>/r{3 f!\R~kzkwu kD}EG6Ҧ2N'һ1v@I6 ^Qk""Has^Ag)n81sn&g}'ϐyy 8D_pX+Ms݁E^.hۉt\K^qMr 2?x~FG7NT c|],6GfQw1}O""ktsрki3XF'bJ)4ɵzOG/N& esaje.v%͔\[nxW O.OtJ6_3Qؽ=:9hE>zrX6;%?ɵ8k<.Gʄi1W)?}BT)t3^%S ^` 1_ ZG,YI F9@&sT5,YȊ< }ث":/4a><?rz2nC*\ #:,>Yʛ )|pl4H045xSÅyIE>9b"8"aO"l̊;&pJ\zDVl8 ɭR=gLrhO.5f < rq[T .7>U(v|@'2L^y+2}"G8=򸛕 ^}79_E=/v$람J1ڼkbcΑJ>YŻxa+w.֜#.WcѱV8G5ڮ8-<-Ƌ l!b06eV7UZsXa~)C qwoD5w;hQ~8Dm>#wuYzՈ9wnJ8%;@&ņ3;~a,-n=da l=[xj'$&ށ:԰9A8h"JkLP}퍺36DB<-"gpYY\L@x1>aoW_'"hyHgV̠Us\zfFs[P`D3/H:C5Y[l.C%h!={IKd EoD 7XsOs’XMCfs J31[U\9s!9,sg(Qjn&fhD/ȳ&dSȋrb<23Tݼ@7 f!fph0Iw;."UjPDH\|pMeAdO 8q9 202GZq< ;\ " M"rF|?2u7ýu"线qwMsCi;͟_oY=5Hy(^M[Wcɯˠ^|g*̓Du?=OmXJiJ﹜%A IUn-] 35iEl\c2.Åy]<cc ҷ{[頺rЧ xTϩ|LG_0c {j,%>$J yJ Jǡ %lGXaJr?0o}(`U`zfn++hQA^*-nEOuxYpW32TDjT3Ӝ̲xrWsbvxK LW$A}L\P:i(ˁg>QeX A˼gȮT +1qmAcZeқ4t8$=Yj"Lh8›#6> 1C9B\A n}O% ,̐zUĝG<-KFf Ȫ1(ZRb^X7ru R&ZG( blzPs krxQ\WTԙr _`mEkfe 3+qOO" 9!.f/eg,2 V ?r-0탦P 5:gd{1Huɋ< w k=C`X Sw:g(Ŭʳdʬy SMAzr_H~2`~ ˱UyT I۠tw`t;e`iirؿEg쯙M^e6yڽr#DWɨ*iR/~D" Ũ\ =H4 9iUl ȏ:kVE+7{!'RJqR+[q`C, %sH~ȋVt@^ɋ- { ˆ+4^A)D#6ˡF0 ŠgqFQ}ܝ!1sX,ѝ֪9tX1`fq:5 ΐt 1}詋ehSr:熷XoW)W0+WΒ, ΚbLP}䬽Z"wa~*]28,qQmxr7jmtk,2כ\w5}qLȯsq/xWA8<\+G2^34ëwͻKC-S8G!bpߚh?7_Vڸv{ç7[n?%9!Ș[MF̣~=F{B@`-"/ "0"BocnD/vN)vH @a}yq6M> stream xSX3\ۂuDIia"lnP(-)I)4yggސ~N{ΥKG lR!S#wzbyW ØX{촢"'O5/a&w@ jJ噤#T P5Kj,6`Ee@ &&w %#T&sH$%q_&EI`5ߣ '{LYQ$`LAMdE"]å7k"i}8A$tVXQEg9ZS>mkڇοKGEp_;TG|H_M%dK#R7+Qi΅S 'tLߛh7d;[66Yo늸C2p #NTZz7byKr뉧zVtѮ{ArӉ_'/E*4q5tM"8c=v>}6˄uLL Cghz&{tǞ}j - WIadv ;?# e961 !M*|*' l+AEt~vJkT{̛ҷ_zLߜhzmp r^ؼ4o0.N]2 ^R{^,_EAp2S]}jDS[] aq5ԫRTU5Ҳq,WTkƩ9Tu}\ 2 /AwY -it\olO4u]K:q-S;;␜Gs x'7?^)4jBǁT&,M];?묤̹]:ѕwm">ʄ{L4uxCюvTY(uiwrᅷ?4n L̋n-r&ӶZ\T,15zhdp9EwNqL ķls/#Ie@"pk;yؐFe2@?tRBuM^T٣grND$Uʄ"y wws(0 S<8Q'D;3؟޺2{bM]WNB"&P\zTi11u/sC5ј=vM0uw\6tS׏w#o|o;j(L&4Ȥ6qw+='Aï*#: )OiPLLRC&hzrcNJ'tR[pt7A+‰olew_vwq$T;m|yA;Y&%L{^.|^YQ(ˠ~Zxn\sf,h͏<#rlP5cdEDO(BBgFc8T u2ubC48ֶ DS׏̓hj3M(p:gtWu] HB4"# ;s@0ҷ7Nw0H )B} P*#`9/oSTG'?-bk\"rPwY "\H'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'0ʃQ~20p<'یJʆa=IcoW-"fgmlf*ֿ+koWaJ?ܢ2"hEEN=є>8we=16mEzjiG/BYi &>y,؋TKsWXwt{vO]YRx^yCtb邨A𫾿|ؚۤ #^The!^/_]z&y5IF_ܻwvP v9A؊F)HHP&xJ[jz_HX8QnitZ{H/ 9bkd{b#v1M=nS}=:>\_[Zhteh:CQG52gO g)Pғ0;bQDn5 2<}S:#B_Dzg(*K,R xCW?7SE2rx0GHOkT~-5RfS[~NfgK7o/Tڑ@*:^&hvd?O Ζ /mq-R(Ǥ%*;p5+~˫9$ûa6P_e2vTySFrPVL5 s ΫH#/翊O^Z2[m2z կ (jTٙ}MOR#vO)h&UCPRaUʄs莳He"K$KqI*z`twbsv;nԖ^?yrtrNQ{O,fL&jApet:HaiyaPH|V&\/}{2Vq%6 E3.mw)F8>f[/NOh4RF*GS[cGT|/5WIEw3jwrZb%"-roJ??5oݣ+ Q+$hbk]"2;<˽TZ474txU3O`Yes,wLAMW&b gn{H/1:+i5=;.[250YKOY"-g˱laB,,RVS z^|b5]R$~RqHNOUw=zvM ~Ї++d^8.KQiZ*"L ܏C4fݗT9IJ$y9ꎻB u-Wb}07 јS՗@])2Y-;C4 [SjJiIΘ /6n \aJB4d{eh~Wi ًT"~t\f +*}yH~y9wǙh-rTHMkkBG5[&4gO7G+N*YT4{^x\ۻkk^ONb'yg;74tt@k:vYeԄ~'Ds ڇ?L eНe*qRm3oVv-c\LOKyJic s$s9[/DӚ؎aPi-ԯ2ºv,}Kji"SZ:\] \SѴ[[)et'2:Pt6QCEꖷܙHK HtںOLsZ0Ո2! )tRJKFo1XDZ?΍a&` 2!6wzqh~r!?;.ǦJܖz"-izb؇јF"xT-eB`R60& ed$̦Jl2"I8}]åjw\H˳gA$9Q"K&@p!diI0.ܽ52w?8 N_1$I/Wei5nRPzoYl}UF(dL&Q&Q(ɮQ`EQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQdTg'~0d~ZeQ*Ǖn8N}P펱TGR_\_}Z${|οK2j3aJWVӀ8 --֍R8n+ QQ6~h=v9GbdThz㊭5Lq '~=1Qzվ?*<h (3v,jGTZQQ@z8Ʋ/1cc^7{@?dz`dlLH[Կ`G^2Po oޙ"A"_"mߺu0?lv7V.4Rw tVQLhhKo"'~є>8w " F21{~A*?g{JH|[ jQC!pՊaHcLvh\/}{9RtWx/RM,[8zP9N|yod^OOeU/Q >5ؤVNoVPgK"zT7ܧ( WAЎ~ŮI$i.-:נJոtnES(ˣ; iⓗaʽp"&P\zsܤn:mnq==ةr^>\_ҢQQv( PNhA2cZ r:?6[O莳$鼨NN ؟U"&U8Nf ~:2ʡPk1:+i I!_ޞ;^~ⓗ"4*aU%)T>`7Ζntx^a7tAJzbZLhw^mElɸ|ؒλ2sLzZ27$Ӵat7ObgmEZg(*0:,OaLy\˜X{ 'J9T ʚ2|XT:ҴAQroe FFHYܱ,U3A+r(%;mMJW?p-=RXSE䫟͋{ְ K9rLBaorĆhV '#--31^|ny Wh{zjtr} tZw)ʰ;yI{DXft]+bwq%ԫRȍ}?MN/#-eܷ D(ʠ;;<')vf`^>^)ۛR-CݤM&6ZZc1Z4͉HOiQ&'IŶ˂fFZK26[Z\zKh^OMc1qiad}@M&,TNT_jTv>]$VHK҉"-/k7 O\FZviZqoލXl鍴B4T#-sIO儁M7e'RuB4 ښiDMA(1 DZ@XlZ/ǦJvRQt}vGZDͬ:%Kq?sLQќ衐²9߄|A*6UbyLO.{ƊX0dq9LQPHck1#-7n8ʲ?[1 5VU&'W7β :!EG!ˇ0I%ۇ_iT ~7B4#-v%H (Y!2֜Mͤiٶ#-BBEs *L9wq?Ѭ|@wQ2"r4ko} PQi-ԯI%׾vSQxI5 #=+$N lESom}q^QCpRW)sݟ?>ZbB > stream xKlTe;1<3C)1(&mI 츦|C%K"!G0LRL 鬟pPyP4\L"!mp9խnG@Z$f_ -8a\]ga`A yR Bi A ž ۣHH0(nE< 6ift0Zw-a0W7H犛x"!;O/803 9˹gm @te\Q#2*5T91 `al_|X `aߎ́ԑ,XTÜ"YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfe!dfY YHfMY+b^ǽ9 q|H*rއt}6sJoCa|$ڑU25 ; 0BV6 ṽ7pBJzҊ$ %yJdKYx@caoP.vBrApni}qX+=ɂ4v:e=%}>KJZ8 Hn9;$yxT\n]D? |2I$[ۇ__ `:ou|3$yomoɨ$";֢$yen+0 Q= &О+aTae[U&! ۽xȐ8 ^׺~Lrsjhno>B /HՖE 7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P, z3̲@7,P͆g^cubBխ.nd&dF~Ǽ:_C;2рJG[U}&;r4G\6I`a`}dջƉ uOx"H9ߵ-}I_@YmR[VAite'֟,EX+l/4&Yh$Q6;.&#qb0 vmvZ Ҍ bA6 NfoBJ 0IV6ɞZE¡[+Q7Vu,-DVq6-Us--DV&[y#A aM"P _S[I8J&Ec͎8y-e^;2ny."H씸B6AFF/}N[T:}/XU*$<-ѮUPɶd`"JRA2? endstream endobj 62 0 obj <> stream x]WIO󥻫;D\/ I: A1l ;3JbKI*zs$}o{so]@ ҈@ `'(Aybi%H@ RX -&y:\םZ*{. $0g`JcR< #4)aG͑hLI=luq'Bveu]ˣg_yc|: iK2m%V \Hڟ7Hgd,Kn">\L ,BfpJrXpz#8:SҺxq{8MDihp{CK@Rf+ħ9Op.Dgp)8pPJѠ84`͇_{TmKëJs(I./$p~ s``)8Oyxp΢ L|T4hwÜnB(!Ca{8pap7UWƲ%A$IқL78PCj͂k(u|k#DٹIgX9*:$\8œo|RjJȖON)=ZalN}I*{ʞj"NB=cs B1ZE;m>K#-9`{tGLਐ$WZf(8\ĊU &x ŴRIYf'$ Zi2A?E\O+{egTfo 3 tT2ֈޛo52{t̾=XCI( +zoUdeeT]3R2Tuާe9p[1b8ZY~ {mbcAf/XUa"z͆ޛo2{鄑X`wr5qJ"Gzl3d$-z?cYѭ", W`c1VCջzmj=iW*{^3#gY'W8ޛo/$` TDKph'X27uF[ &["}/2 $enb=&ҡ]k&b)D{T訨@J}~6.g8#oyNdp添Xp" `Z X0a)dB&aI{ <,Lrg+t%'Xb$OWj]?!m&9I$W-(l%ܗ i$ &9I~hkTfgښ5C_L&RHdb~jzgq/ ΃tIbA lN7I2;+/ Qh\L & NdWFLl04]( & a2m-l2;+PۤebQ-L$kH{&gz{i4c"uDqr_ &ٗIҞ<ښk2;+ _0 "n`$ǒN25ۜLIg`&Mb&`i{GX0AL5B&67L $Op &$!\K4Ya8p^!d_& cMu|x{$}Ȱ &a\)/)f7B"H0`LL!$yyd_Ij\tck^:&wm<#d/,mNkb}$ݓ!"]ը(T3ޟ-.mh~KiU0I =Ps_വOT%I"ImxloxSla,}-x\?צW$5L2;X20183;+7\|'fwT%$i6khB u;LR$=c!Pv|dr|OC0I5NG!dV ق/IBd"A0D%IqrNlo?ߧ2kF2t`$j룜kYz{i8u buݥ)?B0I54tC sgy4}]70& hs9wgli!p7nTd0qrNf˴/@s`OZ8 hkG&}6&)1i;m솜U܍15q wkޚt| %,8&V7gfm t`{)Yzgy86}7I(Bw!v?sڂIșov0}x=wkoxͶ &ag7F61LB[H0e9bN'iS2n0&FWLO4eqq-H3lQ')n Go{^&҂pn*Tz72҃wˇ0& 1jf]m%1&醉0sYsq&RC!$A}G{~b.`D`jewrɊMM:Bt.L0ϹWd&jŃ^H,y{!InMGLE c&af9:ĠW+Yqi-W&fOA =2銒[&Ɠ=CVi` x<'-If*m6M0I5t!r6~t:zm`vsm]4f- L3/tiZ[_)پ:"7 +$ (k+'l1&D;v~! &L ]؜lNp&hyu}Ie ./]4җ 5o^&9I.\puS}m$u }r[J+]-Lrg+#܄_1r`CLK!otpV6, &pHq{ 4]!Gi@0!LB:D @yC0*^ $0 7bɍZQLq )C0LB85> 4.8Jz 밤[0LN{"[o᩵7KGq )C0I}&^TɤQ}kkD:DJz`م Ѵg4'[V#(hNq &$LVe ]c6 &$9y~LN{vVC0ɑ$!i%]l1ruw &$.\H\%w~_{?k{zloŢh:B0Qlհ~>tUK]$u%(L.Uht&e&Î7xɆW[pLJB6ηu!LBH DF:'d)J\ ^_dX-f?g2 n)+Pɍc:,;dBVZP)X.9"ΩoqsIԐ}ȳ ٪A G j2Az%;NoGfܟ^l1#z e&¼͗_Rrه쏑|Wr(!u^e]C cه/ )`D놧hLڀ-U3ꌾJdOmb+cY!'{v?ܟg f񍩥(S R<ɕrg|˚HHz=Wt6_j4 [&>?SԿƋ/Y"L9B3= p x36b+]0Q9-5VSA,KXL,D v`̯./<{O{i(v'F 䠥lw̞3բwBj9ٿN[%zgY~YP GJTo̾F*3$zo>vgrmu +0%ode$z/LĊ)\I*򆢤#4-}JŶrHU1bn|?9ũB 9Եkŗ/F @ÊB 6Eq%CpWחGTmә70%}>#KO8)u]yllgyy63+4TyGQߺM]7U姄S$'R @Vo_#8>9,85u|,f/^<$׮' ,, )˼y%ˤXl;8~O*!E!&Sc"͗F!ɵ?|z&{v,IEYx"8O ured޽E7槗.! ,NvtuCfgO18NOu*O2\x\'4tu1)S|ܹL$\Z&X3Iv_l&g`3h #ˬȗITy4Py`TU!B("zMӠ[2r['|>K0ɡKҜdzDGX${Vę&5H2]]@ uqB§D04 z-;`uݦF[LҙƆ뺅!Q!8YvT{\5ް_=4ƚJRAQ^bI2)isz:}[ @85..(b B,vmf&s:i9UݔeWx3 v,yRK>yn>?O:`UGF) 3]]ITs{q1o36Ǵ߼GK]ܛ'^^<6|$u}"LɄ8tu^)*ipo2!p>4$$4͹xˣGɵ^"<4}xx6BNOJUKeONwM}}ޟ]#!Ikl+ l{@Hp^ҙdOpOYxRn}4o}%U81 4 YUMk"U]gW‘\A&JdO KvKJ"lIV6+c 7XLx \ݜڸwKDU]: ;OlU-$}C ܨ endstream endobj 63 0 obj <> stream xݝ{pwMI @Bd*Zg2-4cuGD011RZEIiy R;Wuws+=w={ww~s|>QFl{Xb1zL5pJU:Yɹ~u]sor[ %nUv[Wk<Ə?tv ]SPT;eAWi MrQLvmDp,Ru[jJr,KK2˂cz]/ 1 l7 3vQx _.f@-I).+7TAd}a^犾?j.&.ǏXw/G̘+1aA۽fB%ALne0jdr*;EӪIZ2/mw4Qߎ?Mi{ᝤ{; iL2?dPkQ2]q,&D^Ad OꏯF/M/~x7Gwý̏$<7Ao㉖7(<4]0<^ģo>JG&eW1\2ռb2 =< VxZ1aA~"4 1;,+US2SمcՃmɀbܬBu>NsC?&v:2o3&~& MMrVۡm96%qK MM'CᝏzuvԿx7Mn}nQ.d$InO1W4Pίл=>ơپzί,=H~iexJML#-+Dt ApCz ?n2i ̩a^Ya?xhC&SK9Xn󎔲ng6?XpHM9EW>9oID$B+fĻk& lG=dTlޱ2DjLyBzǙƆ vn R[S#IJ2{-%ݑ6$$Re}G=ud `+M)&>~&vLz=HI~Wq$y /kI:v5xwNM^KP\pZy 45!j@]{9/5^,n,0In4M'V5]4w%Z_"Ii:| ue$ڗ @2/X2X4C yƷ5clW㟹2mo&MC'w7ME'fOժ9͞Ht1bҰ sbJd Ec{ |q9Wj]u%%;n)گ%f7.쇬as|`kZ:rye;d ./EQ֪歱ó嫙!z* W כnv tzpI2u:][8IȮY Wȗۣ!g]c)05JYxS_حLl6oOSkf3IWE.gλ~K._#)REP떘b@xXw{L/A~\+`( mȏtZT*´}]%"L  Uٻn EӞi˳g./uϲ/z6u&g,[/8IEv endstream endobj 64 0 obj <> stream x][k9~_灕uW wa1̾L`d6 _IWUOn8$tt+svl~QFMSVVk(J]ןէͳOVVWOWg^su?>(..n7t6)kbZM{g^_'[^r7/~û}Vwwwθ uqփ< :nW̪Ndz:7Ƅ I=K_fMb _ ! e #ø:a'sƟ9X'&`/4>kuH6O/zc±7gs|x{jv zV@ Y@Y'}Yo3+`w<"@xna~2j@Sxp=128;D@3Oy4%mеZݑ ǠSi B-,-jmP@\ɩ봉<"klzѨΥd@Rbu} ʀq G y؟@  jʱt{lvG; {ZM9v/#j'7BD}*6EvYA} 5LAf45X]%`ڳZ]rM*%vWLv"$n꾑ev7\~)(Kp \8ܲ)poڦf̦qPCllo@V?⤄8nWK{zXuYe]٭E=_~ h|ِ֓)nkz!3@# ఑>qw'Hϣ bC 1lԵ޴$c|0J* ݨWodO,Ha,{g jF[Og!\a%8@\|@4!4|&PyKFi'DM育80Y)tP'gZ.[{<" ޭ;KB#󇸆ZoG0| e zxwAW6aCwFd.3NAZv"^+4QΓ3CP(3.q(dCI$^f3fGveʼYHjFPPnCvDM8Q<:x>QO CQZma_YQ> #|DȎDB}meE|LLC#A(% xI:cwe*_1C<)$} %haDq3Mb%߹ ߠ<*ho᳷l"0],aLFQёÆXJMj;|"T@ ÐsidBT0 3 DA2n'؁Ny Öv .15P"5QE3D@PpxUObtnm|+3 T$a؎?P@G c;HON-^"5gb ςi$h*pKRHUW5UQSoXь3;VBVڛmj~{FG4ym|rbJn_'B$2_>[ۇ=5_dǤKÔR$zrDoA =#7"ae%OZm~yv]Ԧ\&eoе 6.ϸ?NL4#kq6m ey#^|IN:fڌI4&\6&\_gL3&-qR7ŮY(ʆOiȞ4ib}Av IF|%rVYM4Vtѫ Y(vk:N4];Ԥ\%kp@?+bũ$y dm\r5joiѬ >T'խA}xP,-}23'/>4C`yv'%ۢe9%,<S{#` |Xq13 E.bt݆3sTVJૅuhNjkV^EQ٢z,}P~TS'YZB"FL ?nR\5@@158' 'zzS%q 92U3/ ixӃh3C`簊@@wpe z0ڃL.EQppuP+"髑dU`vY!TEq%62.*-}~G{Ds`#,DV%.8E㢌#?ίbݳ|{نLJS-FXhVóB9MWl7DXGc L`m[fQcNJ7D85dovi"K3hxUL#_n*"ۖ( ?{Ú퍋*t7_m{sQ=?K}`+Z} endstream endobj 66 0 obj <> stream x] [ڽ?W%fɪ@W%f$nDGQFP131g&iiA<8Eũw_1 ^ETND @188dM SN H cEGGYx> ZXyF@Hq )p쑥͚oy%):f2LJ5@-J 6CPR`|ÔYwn Cf2x顚C~mkgc؈G/g}MCn`71S򬢹=F@*ՄI@ `)&''tJcH8CsEu^Ać6*U)3n_s|((L9#A*-ވ.EK7_-՟3|l[c EAd*X7ó ])XS؁6PjB$ɚ'2tKqL"{RXv*L}kN^N+' tQ^,N35bmͯ>hdn8k汻v)zM&e\˟_Zr[.lG-E3zkVWZ5ŷ˟QD".-xJS~tah&v?86Kʚքu/i休ڌl)F"^Q<#OTȇokg !bib0^>,0 I8< |=rXn \{d[d5 ~o1q$Tv>F_|V;M {3b'>E|rz~of-vUeOe :{靻n*2}e@Q È/Haz:9QQ<<7ym4n=.vR0pn7s]k\x[/hR2N fvs$EF<\ݕ)a n$*B)IS;Bjkö--n|V dDl + ð(n?=x汻'NW<"\!0/՚;^~^,W4.Bo vD\8I8݅''X=7 ;.=n? y 8 ]7|\Ѫ"=q4J&?ػU_[D %L Si `J΋΂i"v؋}1ܠ ,kAWקS|t~lO΄J, |>#CтxBoJQ";#:# +r2}⌍Ck:cx~ɮa6)։ɍQ\qiZiAF d^fs.*)\| e|5mf0q ןv5~я Vuد[ЋAʑ4hR4]?p۪sn^9 ~Jouh`Y9]!iLqgzcg9y9N@5RN\;QL9f (K^')TsjN 8w-0ǃ TsjN pI"5D  TsjN <àx6)|WWefQWmp!3}< Ny朕 eMkBHNkMyZJ8si.X/r>/$*!`<0 mDyYd|zP?OsMY:"<450B;nḽ1X9XF;6d֏^!ӯr冥&-R}b"B0>m^͉*XT7/gq}>,=FOLPhRhGnl`v["(qo?y$B-ݑq<ɟx/E<4QAMڧ'(څdЃ7_)Ǔݎ0w۪gi(jSe~rmajgMpҍSx=Ul)[ԙ| D @sn-]h|xɚ0|juC+sMy¢s*] =xSEݶ@~^NWڍv6r͗S'$34ɰ^TгͲW-kՙ !D9$Y CH6_Į[W'K?l1j3 B A]3)44 !LƗDY3;%1Ǘ/ 6koJXcn_!r}%rݝE9x9ޫ;$'Amc&̽4)5>l:`j BN7'-vWs;ܛ*_1INNZ8y`v2x`q:8St`q51Ar0k|VeG?i 9#+07Q~) 0q9T93iG9]p0goKܶIW"Ǚ BJe?Ͼ5yɦnHI_Kˇ C5y㲒j|v|W?N>v4}}%xm"'iI*XdӗU^-{ahh5HRtݳIb74kbJ|IV)C*Fr ɟH2*(Hf/=}zm%vwaSonwƲ Pt;Wr5sƓk>xnv@|9G$IN>.I)NX蒌 y3WxifWeh~:#,8R2}c PwJXMS|nlL]Qּ2 q[ eÏ=]cKViz9&\eAጦ7т{ItQkKݛN.v5-Ά4Ϥڭg*FsL~1F(^1fmqyz>Y'gĆ675v\P菫cM?øgB.vۙR]_+d f -Ow,3\%i-; \]{Ҧ[3L/]Ԝ75j9oB%Yv9[Dmơ)0b8q0XU'bf @$& [m 2nuHr:X$%:yv`|蹽Q3FKµ=ce8 ~Mo^~h9vÅ.Jw7۟:\myaB^ɩ-~% )'\ns♥UZWP8D5>)45=cEOl':҉?tQ*V4t콾͈FRk( Xv:4fًpS`+%AcUg7EĦ-'J҇?xX>˪3v)3'qu&S=#kw׿zz0}[kcķ mH-;֣nxG6Dn˟"K 3ܢsO[Iz8" HgZZЕ) s߼QX.}>Z0ق CUS}LZn\n=j&֣rIwB.u]nY9lV,ZC/{EŮ˵V=!l="jVg-%Ef'H@{\MobaJwZ+ua 4 ;4YH %~Ȫ7)H2d>0"ozAZ*w9skx .8 } SbY9=vܔE]7' NU`ic5=VG݅aS4ev38-Ūqsz&z6lj'{’v),8fJNj(v3*;Ak 枻qsh ^ r <㖹tn;E#2@UX.>d[H!}CG I`v.ߴYy׭9OGyr e1эvaRaJ[s<:G99yN9gsɐ;FR 8WG*mG@jx>oώP> LjjwBv˳ۤh4twHr E!)^oZݓ$Vg${GqIVv`͛_Q<ǻ@ p@zPr zGX[@҈xN | IJK"}m*=ӧ;}!zhv֏˶3baMsbS;pznj󻓓ePFG 6 Y)<=96ym$% @{K(OM`<8a< JR75qcE]yŽM\У؛8?aTOa{S72iA>CO'8*ϗz81_0M$HAsdȅT.*8".) 0QK>ߧtc{zً;}aG|y^%.5ЎWW#`f6G oK>{hRYYqT|=)It.HlsύYOD $i"NIB Uz.HwNh#1;x+∉hgpZ>(Kɖc*֜:BBhN 6*$Eipж(&Fxrf~(ny5F$4b,4A" i+׶*8;}-"kˆU1  "8iI䜶_ nz> stream x{twC/I!-UPV9C lzN)XP!D @;,;L칟̝ofgޟAGu꥝(ҁ@v mv`v7WR֡fH Šp|[KOdVŠ2Cmv+cGZoV)حD"JXQt(n%:L,%-y g- v %!Fqv R#1&DӘo(*f}ٮCbA5$<}nY3FH[1Ji4c$牱;TҢI Xi6X . uJf-B:hŢk@ޣcS-ۃ ŕz88]4ԡPV dH(tpiB%BX s)*HHHj I+vp`,)~ Pʟ>aԡM:#%cMՊEFMEf)#ۥ1+G7%E4%G~P!9~.pePÁΧ>رʢabFNt#9gVYOX]d/ ]M_k ¶I (l̑Ks)={'X-Ϣb#A# -LI]\=^C%Y$u!g1oQ6K{½Gޣp ½G#pQޣp({pQ{A({= {={o= #tpyXw) ;pyP4T=KAc7#Lن{{*os{ *;pTg0{[#x?gd:i`-Xq{Arz*vMR?{6#0^x{VJϽG`{ {={o= ivFME+V!t-R Re{~Mi>k喆,Vc;~>zByFh&mR)34YvHM!%14YwDVW[/,-5@BHq^2b@J䈻Ȋqg])uHHW*yWWؘ.I넳3V U<.NChcQP:Vl|pkxjqLwx]DYw~3j/1C_e[ }Ŭov=Xg 硦D;+pcR%̥ Hv2ym-00W CY_2xA!X\&>i #S#tH JZ]`5;Ë}#XĦ)x͑$?n5*;k;h Fw&~T խ%dRr%Ҵm>.bu(T8 f.;Bc߇u,TK#Yж}돩a !3O=zzI%O]N5#/tneh%/kU&Vʘ qgX 0땫Ttgme 3̨UX]Oa5`3ށc&Clf>U.r|7Bu{U-vwȄ I1rv T:DaW1Srr9Dzb5{~l\sPCHo a u8Vó3ҿg!>M.fAWaaq7]*c!() -RE]%V«ڑICGGŸIbZH SW:Ap?Eq78Q$ O9qeFtnHZw?-`=y_Q0wx>.MԪM ѳbRut2;8l<}i7RF߂R#v+67 /65Vx%F$1 ~e1~0|LJ3UVa]_Η." φ>#?8s $+?E4j*k$zlCi`C9ݪby(%<)LWDyb ?EY$g0'J=0w,+=^ox’ʄX\2OEj橝OE-"y1w /ԂIZ|B.0aI] }E27V 4lRJJ=xg9jqBXDkK{50Dn+\C7C -xg~Wq9숯?l)!. 4ھ틅H߷CF|_lUs<%|3q_kpD^ jwt^&i΀+7شFG $綉QiR>K{1Z%OC@;TmߢF\WWڹ-oJ40tξ]nT[ޣAb` endstream endobj 68 0 obj <> stream x흉SO2 EPtB"9zB {p_L2!K:ߧ^Q_նo~W_ DQS]33E2q8I%b!`apc`q:m' &@CTL Q5E7GLXe۶]0E"N c&\ Hʈ%$@sbӆtFCʦ0:$J1b^kO) 6@ LjjJ4JLj+Jґƨ8J4 &M!Y+ I<_ s[ZԪ )o9szDֺL6SIN =\k=N9jxq(P !Bi]>VY&XBzĽWF z?iĄzM:BVXzS:2٣OXih#+ ȡ $ dPJāz F&POF*[:2$Zw|\v O 5 aKH(:A|p Ћp?PڠtoxTJNٶda١4R8Uٕ.}"HL*SWl5cCk1adKm7/mȃJ2׾)~xNO|?ӕe:ʹ!GsFS.e]#C 2Ҵ:JSNLkK⇙'?0->V0]ǗqX1a= "-U}wgT=c6AJs}^/x8bzh= o,?rt?r[7i6-|m 8rS߹UQ\R0.Z8ŝ_{fYZɍ_ߧ|˙x}ٶ}۶iBGQ&jJ*PG,͓j:E5QrQ;G+TL**#@Yk8wS;{/L5y"c"L92ֶm/3>A2j" bQC={NEyf֏Qk\ 2 iKH<wo9tGƶxDHv`"!}( sJ 9I'Ź%E9z|ZРUx:?]rݙsMr[%Lj)mj'I&ZǷznV&5!}ŖLaOMtgӑ'?ID2Fl%#;tTSql\~}SdzS aIu# $ID#r61>zm'_I6ՉT]N498e\k.CB&4=o'Ys0waݧ#Ks:SUV7Q۾ù'`MNU]\>ov]-ԗCSM"~VF4gw2 nЍ#.CftDkط&LhiЬdesdH١Ej١JJoC=s#OyrZ4n4yn9Eˈ jk?b_yJ俛Uof[jYt?RtC=۶ӗ'.՝1>ڊǽ_iͪռk|fwП3KXmv*lT|iĤ!>rF:o^Y8NXN kh 𭛚zfN8fjIP]+]|mv:lg &t%)!9?Q9ó'&Lߡn)(PR[_݌؉Aۢϣ` &ۣO";t-}OGIzgWYݑ&5Dlz=5^"Muw_R~r;Ig7JH?k;SXjX"_S4x7;pW)| x.JZ~cvf\Q }RI 1FIj?`{Hz=$z?4u6U{C NƦ^OTɽW1k~ASӧ%=D;q%a՞Qlw2VjM s綧TtUեk[S7vY9ag_m+HG$L4$Uz'G>ڟD(w|a"S+B30VՕNbU?{uk+nʽ[D0,v5S7zG$i;ryw3;>e*@w^l_Z ^>ڙE Hb;_SHޑ=?􁼤D&f!sWv-lFqnXzJrNA;>e<%qz P: @I0P@(I#a$4PF%@Ii$JR@I% 4(IJH%iP: $J$u(I @I0P@(I#a$4PF%@Ii$JR@I% 4(IJH%iP: $J$u(I @I0P@(I#a$4PF%@Ii$JR@I% 4(IJH%iP: $J$u(I @I0P@(I#a$4PF%@Ii$JR@I% 4(IJH%iP: $J$u(I @I0P@(I#a$4PF%@Ii$JR@I% 4(IJH%iP: $J$u(I @I0P@(I#a$4PF%@Ii$JR@I% 4(IJ"8%9yJ2erTe=1)`Ps$6x Xc*5䌰V/Cmʔ$S󒒽i X8Q`2>Sd`_=O%f㗬 7NiXO;mmAINGKDAH.-#⏆皔"S+2zi)qm=vcvGtbrQ==6/;=m/tS !Wg 1H9Er2b⾤*pf9SZ\EfOLY{"F&3o߰l !?:$)_ -.|BI0PzWr[& vvw i_gCsIK5/)EmhI>jfO柱}lkxk槔UڟEl.>c/ kLfR5NBRk< 4wTU"I"2'ek6f 豯9-#Hڈ?bvGT >g~5T-a/} ~s$Sg$<ڥeĔ&`MpVrj lDqu$m>Lol^Ͼ#' ;{#:ڟ@6 )"圉@sV<0A:I}K_/ݟeE)lqFx]đ=йqO}eHԧDaߙ䋴{cݡjll-6&GH$ ~$'oe7$vfge;ۡL943255~&\=5wk:RZ)<|c9^I3bڙƵK ҐE&˩`j$(Y,?zxՐ]%دn,JD"$벒$Z spr_H-(.ؒT"%,/}7ppOV˃߻%59 I\cF@5F1<Z޼k1;Yݜ_XWYKAJX4g%[GKOiYԗQҺ2mD2Fln4N^VD&†2t$@?m I"`'z28nm"ϧ֋ޫvf;:xo0{a`r; /4uP]nd 2_!Fn# KPiTٹ/ޜ<NFy4m~;|4=PB) ?7O$8C5QOR1a/y,nȫS$}gED4$*$/n. /dOsݐRFfd۶N[w~황X7Ѷ;٣P *qytՉ{/_wPq\ă֟m۫On.%N{NE(-biE[&np^^|!/Rk=bsXNq"Ҵ)Ks~r[4q6?\BUCffضmo^*~hp S(\vE )֟8ҴF/zhn?,)cj9.ռDHZݘ]S,W;!EW]PGnWS"!l )mr箝QJ""ֽ]\ay[nWy}۫'f14 h9o SRVzdMWR")&I[?X'Ȉ<޼ _(Z콾ry۬?L8 {dI1%lcO=Fw,DKE(xq!= }Ȟԕ<ùӬ? *䔁+oɪ ߻6;~R:$=GqƐi7G' bŹ5E nL_~20יWs'.VYzj9K4pL$,IqlKc=^ۉۙgR|As/ hDkdTnhT+m8i19lm?/w QPic4 yO3^R qHUkGAݱ^mu]}?3mv_ֈ]FxU <(Єaݱ}*)[.߼sy UζAY~{ RhWz*IKLU{ 9\ݱ,_vۙ|j(zj.a]{j$SKةֈbP32⶛SO"Kgo~.eS}6{-ޜ*/D&&&Tz쐿XZ*PMNkDC35c9= ϬHK#9;TLwf#HSmvV=9I)/]52"=`X7GV\Ũi ٞ5ӝa=|#ݓTBO6;|i2TM)AY_h/N5z}KJJoM CɻKhzRJSUj,^y$mg֏hHkOE#yIƵmCxJ׏w"SNН{w^A'#g|ZI fտV&n҈##pYI,Q4 Z) ?B%3u3S a0(I S3cIR1u/vM|BxUĄF98)Bpj\Fe2a Wq&-\L9 NXh7+mL'zD@Whg{ z8@WJ[y g@-[ {8sO4PŸuhݴ$x)a/;bzD@1*)%E)B'@P-p wpSR#gX z=Ih08gh1My @`T.OA \ YQH/&1 .KJq.(86:C}MřH(zD@ќA谛DʋEptA*JbzWM 2M}\N`H(Д[*yH{'p&`Hq$Icyﲉ"=/ 1A$Ic ךo+zD@0+Yt \ tU: +VP1q3pV8NtpGNuEȸ-Pr.$Ocrww\ )IFB5f(桭Vgw.``9#(h[yG쬣>/]b=FvhŊѨ)MJxڏw"W3Te(g|j8OjMtZq#pn3G1{@sJggq.@/duնS[WF}<a65&B |A#NH*uIY khkMxh Ŀqt /D$kd endstream endobj 69 0 obj <> stream xytTd$ED ԨVlPj+dž*6#=m]D)Dl.QFve@Xd@Yd&33K$3w~9|~_ߛ޻?M!]t'"c'Sk$d+^@w ;Mx,5Z$znGműPAZ$74VQ MBm-!7ej,iEM3j,JBij\"X,ȵ#$:(/kAmD wa^ V KiZ2÷lZ#i7j LzQK0zK̕]r>Rag,SK0SK` G-Xemq2%V$ 82Z}e 'P;2)U5n/ p4㷕g]4^d~-́b(EPB}u5` }b+ԽXfڇp/vd]Vb1V LV.ȅ"yԏDY);ignͧc-&pA3LԏBYi` Q6$ ;4\PfNᙋ1w+l:I?Ү (E&4FPsbkw yv*5Ger 4^vL{#&9%ztA5FI SjbZ/{>ۼ'c_*85^[-Ht(lG^5 D24+w?S-׺`ˎ;/AXj9X~ Zv :ϿgRaKqhّt  ˲9ũͩ4QBf9Y.`A3~<7SàZ=yj iW~<Ԇ-P Pn*#Q.лb;v>ZD3j}Hk__t8IRgN < I&R3񂔄kwjH&Twnk-&mR sBZv| ).Dwvq  (ղ3yj=L>veARQAi/P3'ܤMʯ58ߪ㓓+'2__^[e!GHjAw/Mg/Cy) /\ڄb3DqD39&^]57%܁fYA1][6Jz)m$9̇-9 *mMBQik**mM-J[SiPik*mqTښJ;J[SiT!TښJ[T⨴5v%ܡ[=m=FL`eqB6_sJ7m;ӎJ?m/O˫HJے[ϨiGk\Ҏ#&uGŭf}4>v\觺To܁HmIcﮥҶ mޱB6{WD6v; 6nSJ3m߫Ui#p{6^ډUi{ *mMBQik**mM&$%_%I*z_^7$djrA[$s rs*y[^VE|27s'Z΢~2>c2ӆVjdXrRqᒋ?ݲ#&d_S+8H$ͩwHM[ Q+0Q+֬K{J0ZkZ2Z"xZIw߾+a"ZY8Hf5R+$ZIF417j\zx[ P+2R+Y pyfS+0nlkpށS l < bV`2VR+w'OPD˭ZM%Y_~Lj&Y~%;б V`r,Vl?xV%>V`VexZəzavힴ0ʨpMF'*R+r|Bf7&gA^ LC=f/V`r'|L@h80.!*OZ0Z y'~@}j\΃r4 R+lB?|;!jbޡVe~$mP+2Q+ , L.y'B#7PT@j(j}:;7<(Hw.GBÃSp:;6v6M\|8jOgpAM2͎\kWQ80B۞. %dǻ)G+33%u%GLRfTJONm?T9O endstream endobj 70 0 obj <> stream x]o[7+x@i~0 DEhj{[d&fS`HrtCKr!;eGewz\zqǢ$>o⏅uݧV߽U?,zΉ/|E]__};evͦIYS)[wN$5[ݸ7~u_qw7FZezua7*e+Y>.1F=~3kcˬ],+!DcҘP?01ۯ38fX5LVdEoLxs1Ca2#HԟH|h6(w1>_fU(O (`wGy"" l?'[i U ow ݋tYܒ]ʢHhFu-bG5" G]-p]G#s\D+ Ƒx|=ydk^m*_k^7*\(; AI"Np)](9h@Zr*-_.h Ju"$u*ٗ?HTW6 1x&f3LǞ=K"d)qj-Z+<> Ŭ+QFB-X?x IyrA +y.v x=< 'kuE1wUWu- ٗr{̙˩rT㝠MJޔn̞~'3}tI1qxWB0Dw@bI(a[DsML-=ǰC2 x"r$ɣn1Dn{Qg <F6bPo ; qpS%ڄ[Q8*E+Gp*u+!.OTxPDn9:HQ􌁶sU(yu[:MNjo^ DKƅ:T!?5  2Q kct(ʭzFѦWUG*Gjb tƹRk@ e['x#, )ļaHyxq q싡q.ETZ3k,)ƄdUSD'gf!ÖR\LRclN9v42 3"C,ynƲWfiXf aW⋠ P`IardNؼ#VbK+=-[Nh\&&|Y/[q{# bUWVW" Q˵PCq!tJ׳^[GCBU_~gRuUWB:'9-=/wh3Pľԡ j՛tՔg.w9_kߒ 5aOr#p^(.8*5lDEyB]W<0nu@$6 z^D Υnbp"c,U*#0zo\XLuh]3}"O߼]nHow>`Wl![9p˜gikDA"$JTV_͆1o5<+R'cꖈ(W'wzie >v0#--x~B;ⷱuGEX/d;t]UNO O`9ѐ'#ZK?kÛi. \Fr:*GeF%'Trd`gU *T}5 nÜ^Lc{KXX_p8>yޔH4/ ƹl5⽟&.=OK xax2܎I܂D ubG*K+z;Ys6i_qJNG7.96b]˩xOg[!lJEy} `KZsLi) ǤlYG|mwr?Qj endstream endobj 73 0 obj <> /StructParent 100011>> endobj 74 0 obj <> /StructParent 100012>> endobj 75 0 obj <> stream xo8WysaI6 u 6k ܟ̴c'sD3N 7EHҺfGi?ccch!{mBYG>>_ Wn ڿSqvԧק󳟯y^MPFbxW뢷)[4Au}^pC}q῿}>??|oWu],7BD-*e0+)m,εՅOqjRVZc鵯}S}T^JY#߅M++0Ϙ &FwZW򮱯0hm4>;K4x1;8e2g4fhW:qljƔq 6 ! (֎D#i[=|,,X|gͷ$yfvԭ9z)<}HfʸٕIt7t[wZm;w Z9mDްb Z ׄXBE,%n:]ppuV/Z=T$֚2n՞4ƹ7"g F1rި™Z9wy gNVw9C4n@F`R{mhax~Gm}#޽$,FuJM{Q'[y%[L.j)yS*PziQu~JcC6uVGn$pn~f4AÁp>]c "\w6l6Cܾ]@yg(gP餡C1U=^ @'9{,[.!VZo۱)szA&Y4\Z|愃^<T+^߿^7qz ONz}z]:Z\^?ن{pWc4"GgsNqɝ  cc T^oT*z齑d;bVHU "C3tEH0=[ \Y򪙫-P&QQEk81qO`؍t0ncpz=5ޡ׏UK1_I#pD1DFi]Yx(vIp}Y46 `&Ūe{Yd|M<߈%eZ^:+_ssyZ4 \uhGE'8TXX 60Dn bMNziEҹu/TLunsNo/s3n$3\\AK10(PNَ>4ih#T5С\P0w2/qFJN@m-gGfʶIFk'k1@n: *" ֻKFۘF$y[짵f˵FnydHAėGnl $V}bwFP*?ġLi)t(cx,r0%_ĸfp.F1|P$wj0qACALPVOH²EFffVÈnN#zEȻd/%o=g0Mi|TҘ"]pFF +(Yp?6nҐ/ydyQ~ؑ9J=Ү.R"qEɋ@EvJj¬s/*-o$B1"W n6-8.r7$>)%HZ|ZM:I&U.(HR))cLc74b3;RozYǿN!=gRcl9E}]Z4BՉ#x# pž#02R&Be)DY,˘,i͘fIZQ RpxV '̟4Up,T,XXŸ{J_W229s=SnE,H}W :g˹#є4MHT:T,0 _fݥ;g(Sj[q'14Aa+dԠ#V|V$DV&a5F!l{%MɑZlxS\1rJ ]#JYs_<.8QG¸D_<+$1"M܌LN>`-8Π}q)1iPUaz;Y yYPg> stream xwT1p7X  ‘@F@P"ZdAXȬb1WK-I6vHm:8Nt؝gB;݉&,;afM*,>_޼ym2*SOˎs)M&ąW~5{g )5<ܛL-g>u|ODv'/_Áǹ" wu ;UGB_p8ￜp8HHz=i᪫Q=_ww$~?UK/sz3̅CZ[ݩYuJ=iT;վ=\oS:~poyғ 's/'u`#?5S!~|cZ+ï},˲mA}޼ya4ZѣϘ8Qei~?K$|8S]x=n==%eqWHnHYTzbpW8 TzbpW8 TzbpW8wQkmǣ1\r+ ";v쪭JdR#׌ŋo۶-p  t1S 3yNĦM^lk{{މw!)KE~sاx !sٲePẕ.9':t裶 _Z/x~ݺLS[ҩS{L^F>OU`үã1\r+Х%0}*+ŏC,KH7mtT&/eFQQx|>_&ã1\r+,jCCC&@.9.r?%1\ =%1\ =%!6mҥK̙ UPPbŊ3gf2ҭTzbpW8dWSL B`p̘17|5j(gfQQQ&#zzN'Kw~W3g,**?~|QQԩS N\ӦM0a‚ ƍ7wOϩppjժUiVVVy3fXx&\%%%]bE(Zr͎S]U8,Za&d!4fGREϩpp益&B!4EgY h=3\.1\r+ w6#0FܓI =%eqW7 ׭)JO  pJO  s2sYģ1\r+GcpW8Õ<ţ1\r+zeUVVf8Ovpk˗/b7n_؛-J   Tr |Sww||Z2'4<@  ׬Y3{yf̘!~V8tە+ Ts }u盚^ݱ#nݪK-[X8éEFe4ˇ﷘+));ƅ @"v%@`ҤI999'demۛ6mܺaéw:ر}ÆO! .ܩ32tתUjf,jWbEEESL1MS/\7G.|u\|Y- 2 郉?`s:PM6l`wxƍdɒ|CPnw\--\=~Mw\>3\21&q+'MeYK,5jk {u_?Ƿ]4`?1&ӝ3 CB3\a,\4`0T2H]yުJ}k Zս{>xdc0[%*))Q=5+r?9?B1\r+rVqbpW8 w~gᢴpp.9N]1\#%i+kcpW8 wpt  ]451\r+bF:KwpW Hpp.9N]1\#%i+kcpW8 wpt  ]451\r+bF:Kw֮b555p,XgWp  ]cXMMM$FX,W;.Q_GcpWl4M񉊡P(E _-+|cƌw?1Q.9.[,jܹp&pYo/--#yT8Kwʮ;~<үw\ӧO|u+1\r+\v5a„I&UWW;6b@ I ppYʕ+M,--uyR~? 2\%eqW+2|,+77w…~?Q.9N]PG:KwpW Hpp.9N]1\#%i+kcpW8 wpt  ]451\r+bF:KwpW Hpp.9N]1\#%i+kcpW8 wpt  ]4ܕxT2HEiWSO1 e 'JNTϥޮnzj۶ O>z"gOv|~޶U2$<S= .S kdc'OHkъ S[>{vM^s볮dѣ8v“O7W;?"sy>dڑ޳Ϸbfs={<_ag,57~d\ \ǎ?&?u^ǹd t7ՓH7?ҢvO&>ngOwRLu&#y<K&N띧\zaras_#S2*q+_*%{}dD|󮮞j]v~~nfU,ZG݆޷m;RD(ߎݓLvlb+UϥիuRa<,+$Hy?~߾d_2yq?z|AFвe*>m%>?o-'A MH$P-~ղ,׻mzhwZ+_ҝ1"/~gIIU='pݬ􍩞e.}Zdp|q  p.9 1\r.Åc0\ pa@  p.@%1\8>8Kbp|q  p.9 1\r.Åc0\ pa@  p.@%1\8>8KNÕz 2* 2y5 pbJJJ,˪|,k~_Zh0\8>8KNV5k֬EUWW[ -Z4k֬Lb-[&E1.@%'+᪬f͚LbAʽÅcd%\~_IOD&Se+\} R  ᒓp|>כKI Ø8qbuug4M.9Y 뭪}-\㹃`{p.99.Åc0\ pa@  p.@%1\8>8Kbp|q  p.9 1\r.Åc0\ pa@  p.@%1\8>8Kbp|q  p.9 1\r4WEEYR.@%Gp%bS [O"\[O[+--U=Pz>a<%%%*++,+䨞I(ĦMgmC~uϏ-7 \`"&tiY,4 X3 U=s ~|˲|>ҥK_ݘ,{eKx:#GT3H,JpᚚԫCPaaک\Z=a̙3'4ϠeYeee2tW 2=@\)Cf'8?zAK3kR^^v*WTb\{ s:Kfc#8Kbp|q  p.9 1\r.Åc0\ pa@  p.@%1\8>8KN g8UÕjժ.@%'+D"i~3M&Se1\8Kbp|q  p.9 1\r.Åc0\ pa@  p.@%1\8>8Kbp|q  p<@%ݘQ= qHB,)  d1˲T2hLp޵z}1\7m={mjcMƚS bpÇ}D㜵UOkH(]ۦMm'~as ӿAq+yѴoߔ?y̙G=XWzDq.uvtv~}9K&U".ߜG]=ؓHEk"uCgtl&5o\\ybWקݪps\8K(~UO ?9cpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ`0(b'ۮ3fx[ڶz]O2E8>H$TOmh( P4ZC jWB˲Bm..V;xDbŋ*Ep!{{Gu{ɮ ˛7o^UUW(W=T>|^=+Ws=SNU;KϠ;ia9\n\sh+0V\i C.ӟD˲,Yv*nvC) MtiB(1[twi+O1M*\⽨j߯[ 0 ?|m rrrTr w5jԨrK)PH$"FW;ȗi`{5 cɪ'2hWqq)sWa,ZHR2\DDϟz=x@?\zpZKg<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%1\ ]. pp GcpW8 ģ1\r+Q.9p  pxT8Kwc@<*%]Q=.@uŇ<UaaYtpܣxCbW"\.&L\[`gA{s;wp=sg3ײT.T="\o“/]kUϥiؿԦMƌQ=>ho?k۽C.gӧU;x7XVPz=~ώ;ɓ?Ku:/~tƪr+ gyYY…guˉھQU|2գ蹝;{^I'|y~Ci̝307z^󗔖[⭦[[Q$gz3N{ͪgWz>mQ=~V=֮-0: 'k֓zZo%>hksH8Nͪ'ץxw]D_"ѓHKm[?qӎwW}?8%D~`z:xgO}4z.uorֶ{Dr"Kz7niJ=ď[ZNl٢z.ُ=vm|"ѓL9NO2M endstream endobj 78 0 obj <> stream xy|T?3 XI&l*V@l iP[k-X* TT4`]Q}߷$d$*VHrr\NMf=!ωǠ1~\̻[T;csA6IvgDcIP'A%NK8 8qT$IP'A%NK8 8qT$IP'A%NK8 8qT$IP'A%NK8 8qT$IP'A%NK8 8qT$IP'A%NK8 8qT$IP'A%NK8 8qT$IP'A%NK+&y&oq$m9}&!G%oCJ"AL9NF8)KrW$q@$ n4{1p$)ӎ%,1H-a$iVGRz,9qJusG)ges10$z $jΣs7u$Thvqp$!l5ڪ*jIFc3d<՛" M$l }wVE6G$I?ۈǐEI b 8{¿!0$E $u׌=/<>$*7y>dz/F>$C{^7Azf>Cbs$FBRwM$.GF_Nb!CaG Lb<Hr{EGW~ LnJIҺ=fJbHn=b;8$=a#&pvk޴_O;S8@!iDrcmwC HbAI͚D6]#aM $6\zx 0'z:$. D< @r%o0dIz 1$|-BȤ 0'ogo}S0'5x- 5EoζHI.|dA>D#8D❿B8rDFraբ{V:D0x^[)cUsl)X~ψKW*BJ"=y|@yylqD^D&bfEL1IqWHQyI|(n^D$F K$|^L%6 "D· hS"|t(}dH7&j> PB2E&\ σG G&b{gDp'Mo,e'q#BHvFC4$|힄W0M$yl#FoGCV*kוּ~HoF&,r5 !{V>]a7PC[,%$E& (8!$rsLrk29F-$]™^$k7k&Q!BHad)1ֵWfH.V(lk6񛘮$WHo=yv67="t IRȨ&I$u 1Ny?)'%BHۂ$w։`2'IZIώ;QHȄmC=%I{6Uo$im6NyvOu/JhښPә & VIYxUM D3m9Soc/qebSNBcWSnkiZR2CK(Mg?|Rz#D@iGk&JiJi3O^/hZJ)mdIJ5)wPz\#Ie!(|l~2:_`Cǚ|wOJ%攕]f#OI]wmO>4T!,f*pQ[h({~~*/cC0Iֻ$.f, CοGH7g—:^e̕,[K"%5ŒLd2V\^<ڮ$@BoJ*pv)0N` ? T;$DE'`@yU􍧑$RM$@B~]($93:WI7;>h} mI_C$mjDnvU}4m$ o&H8S IzQhd\MIm9ąq٣ !!:kT0$iRoH"w_틆z8&H<͑2?P07 PIeѫ#ҺiTI@rIJ]DnI @=$K}DeĜG I’ό[C$)Ѷ!J/L$yY1-$mͳ:en7"b D0ЦȦ:3 UslH$m WֻقʼnHdic Əl:V:HV-4F vQ$VFIpꖕ pVOl[7SI,NHZ/Ul$dU$)[lEGop$ HmB%TuNB&"M#D1Iv -i`- AT/X1Ikm*%aHd-fL6HH%I*-1M$~,M~mź寺$!=i=/ksGy'ë${Zq6-,OkfvVy+ثTd泫Q ? UN$Ez wI3=M-2ߞxR IqŋJM.KG O]Gy⫯?XE)}G>NXϨ#aV DXHfcRe$rC4F W$t۷MajEՕNH:vK"!moz׾%aze53j ze38t nV\Y^Ԑ$~5ML; l!p|w~GO0O>]%X[`/2i[P$~* \*R WKo0͔t,¼T<}ۢJHW Hk{^ݐPA" N\S7Ș`ÈzZ0'T)z^F ro0 m餆% H?@=8B퇂W??{~Uڻ0 Hz]/~wJָ''5jzO;: Mt eЇ{Q` \Yόkĥ2-uOO33BO6E7\B2חHiyP{ɛ8 nI"*_])'"ӎm?\Ί}B_H<w~nIG/Q3qI}r!MQ{Pٶa$9D$}VVꎤ-D@JiU09_H)@rڲ 0w$C!uL a־j+gOHVS/$v5" 69)7$@ mgnFwh:[qC2\U/xsqBqA3(I:$7A IH.@@^E\^dCk(rפ I~ZC{/Cf+S3Dez$ kH\lvHn%\I₭;I&Tn#q J Iň]NI&12$qIa&r}wdr9jIVl'$H<-x9mIHsF?)%9MI:xl Mc(x~u0rG8{Kr!Jw"gv/tP,VB"ʤDLҥz4)dTUHy$䬂 4$2tC2ns 6 pQXۑk!G)e>!~K)ew)WX1#])ʆW[g&9N`M_znEmT $u+0EC/,$qEtj1ah高YK+INjth>j61L)bzsI1B-+zL$Em= 3l yԣdb&i32ͬd=g 3gSd$JƊN֙QgJTD{7DIv|7I$u;X[Q#e5%YFb0Q!y~W8LZO Puf$yj#I9WxI~NB}$Qǰ$b"{DpVp{K$(&K$!Â&A!SgKdBV$l!a]Y)VIdl#LCVId2J]M$7B7L;S?IBԭ:$$ <^Q4L9Zp\]骙$`kQ($+=5lE> 5iJ調 I{YR7-Y5Q`k55ʹ$jkҶ~16QzPONE&5S05~C)GΜ8ߜo1tRlDvPzbIMFk5Sړ{{~~u&]עV[6Avޘ[wSGpEGϸt^'&,Z֖@R[Rѩa~#[F:QQ{!+[.3uf$,B(%yͬt!HRk:QM706WM%<5u!Źɖt)>^kנcs% %QՌג'!̜W 5._\k%v'f1L;zR*S !CSP:Iƅf$$ELB"y5xMIHiPP|DF I\$,b|-ndQxHNdQ v>;;„Hd$uWxwߌc0 >,jJcx6R#zOɄ=0 IPlPuTGŴ6BBrxg~e u(61Xqo!L$J 4JH&GIB[jbvt݌7˚g 9S8d+cqO2+=$6uM2Dk6 1$s[,gȦz)[_~WZH&ʾI3E bawٌ7$~MI`be3 9mtɮ)[V&}s&$5շXɰnT%/l@2"b!q60wajKm|ҭzk|kh$ӊ+,$~FW9ܫx 'k_ k3|nok-$Ŀ+ .pgbuьd۾\TwmrVM2}?$P ޾wx;5'Gv#R}ywQ^V1ɌB6;+:DVÚ6U Ywu]`j: WK>ֽoÁ"*p.X$wndΧYG0@pHEΫ?JؗtLҧ~{8% ?f*In0$!w;#"խfqAv&$fڼ}[Vue=n6 ǛDU.7黹4);GpH:Wv7w$B~*@BNA"d.wE3 6 :Y3 Hd!IZ> xx^aE0ﳗYo&tAjhsK?N0M"2#r-GY$)!Iݐ7]H$!W6ZL"(2\#bcskhG%M_Ep$vw,qJ\R!IҪ=5` J!hNeeEI:Ë9#-(NbAD? y4 JKB<K wooc98!a-_C1IOoA.sBҭr<$AL"x} wj<)-}+,]{KG q"HMBHRz w`YU~h$!=Q,7HcG_JwH11J@t@2R^=H=BFqL׸Co\ {(=\*}mـ iaw\ggISON$K[Iq@UvrWF)83W Hr)GpH>b>5>c$a56IUG kx%'Jy$IZ^B6grPm {N` g,)/aq/;iT_`?Ae6=hb$yuĨlGI$7ViD$5I^FOPVKKN-2IWLAmgVLق -c0I-AC-P,$gGhOi$,˥$9%[4K9fIAW&NzZ]loU^u2tk6Fku(IN o#>*yIʱ!tMndiM%ݫWg5hk.pq$l2kt[Ag ! Hҵru \RHg`$^%ұ߄HHB`u#Q'߂}(#H2wt$dX$}*Z$C[~{$Oൽd7|$dbcS!0 _щtD7 X")`y7sGՠ h'!5/0MHXT(~ғ$@rAc_,CR-eЙiN5X $ifJ܎70l߾>6Ss(S݃w޸6 o=$d@=f / HJ5&IUkҊHHPS8q\\$ޚHT%UԜVEBܚ$1מbu~B#ˬlI+#!#a+5qCܕHH_KM\\ ji}$o#i5;Iqzc IH߆^=5> 8) :/sjd$/Ĺ3Q.\1d,L/b",gnR)IHQqd^p$ D@&+eK2NeiLV\šY 焐L@L$H{ D[$$+/C{C,R9IN+, v[b#!Z$HIzG_^ I6¢b{q ?bDFң\uIƐDIuIH$S$o{M$$Qp, ^-oo *D$E$&bգ;'Qw | aUP_! AM$G1Kr18(qo'H:OB=-IϺpcjhn+".ɟŧjdN<# >< 7J`VXCzlNvGCHBy&|R' lKbEa6{"|.If!Kr{EQY'jvYi6ɽ坜1ᑤ;wbsY մbeəτCɬM nkXP__,NE8&lO;N2ue!kwf`U`)ܗe$i9磰7H+i%?vW"LI܌&k%:p4ʻtLp'2a$h1Q VJ2 vXc-`&JmP4te\QȈFԎ ^,IL$U FG_EDJGItU}8j"iv^LE $#jԣd<{L$wc<.u7BJVQ܉oKUdLdca &F+Uc,+&])샋.p7@D@yi3lE?"x ;F&[<ɓ kǑ !>H"{eC$ck7ݣ$'T=@2AY#;I{e$L"$3׍;J݁d"2:IB=$7z IV(;N)܉d:Y7ILB$N:u܉F/I`\2U ɦ~gtml%sܤx~q$"~%ZsjJ, J7ppXГZfLLJiq9I)m9wJ)m-z5 PUmfQJK~w9''ZӾүz7G)]p%r)>(7B<)%ܼZ L27 !\r endstream endobj 79 0 obj <> stream x[o7)\`i^0CHjZxMqS`?Bkl4<$53VRQL?jeQ;l{?%.ڠ>~I}^}Yym]|Uߪ퇇[>:Wu~~ۿ_)...nlTքnջջox:>U/ԯ˻/ٛoonqWB;yv(+1bkut}\>΍1ͅPwR[LB|/h1ͥ1MxFJ?"&vӼ.&ލa4ƶ}|%wveD*mo7;svv:gBfm5^]62vȘYmc ,’KoXۣ{Jlfb53$vbskcy\xTxY<0= @~; s?\:_9HF2#4V\OuE4!}Law N+F,4$^<5=u&>xX`'`a:IBiRƠU!H#)"9 ʉ$9&qi A!AN!˸KiUx*iVqt0TTTJYFQbd 6 5#rIC$bķ~̩V0DžY@EQQUCE+2h%2e2 +^%^X @ٱ3Lb!9\CBH+b zPcB DǤ፤^ IKa)v KT%r=8x#|G,TI=IR&1N7=* S> \|T izu;ɱ!p9g0JCA1Xg1DmxKvqZ"tiF59,(.}ж雸|> ]\^Ao4o(ok(^,qRUPUX@}1~w't7nvC`D=@Ad0 /itf?xyLgHlVrT,vw$BpiO~GڶAvixD.}UOfEuBƴe̿ç3O\ 2ߵkˏ#ay,ҫarx^4*ၧ `ӏ~-}%'Wi 㯒eY3p/efI~oxlVL/Na{&EǦED'L\-ks/u=Fmhǵrmt61xm\&kL*΅PW1klz[?=5^[eR#[|Z\$PHJv^FKc"C%wm*7PCTn<!ٯ eؚg;U+NT=\p#]Ӽ _e܃(ﯧ $ 7(R}HkCk.Te$30h26>hC -iSE"t4ycN亷Pr? (~a ,vhyP4PlIL3s~" +y_G| x+0\AII~ӒS]|.r,sUϱyD\$a YrdƓ 6e=S<<Tލ]dxmZTmQ^]ΚgLѻ"P2X F51ED:bԆ`~-_0UgҜ-Tr=w+u-tʱPuq?P#'Wh)[ q~"Êq3IUe"^PvFۮ+O7M[k]GMoqG>n,B^0 uciJUSNvqߗ ݭG6Lx_̚.Ջp+{ t|[f}I*|Lp*l8+JG \͘y+Ӝ+ċڂC`γ7I38h#M19= (j8Bק$S~\$v4M{+M@9)w(Þˑfa%R0AL-2?r7 *L#Ss]]2ܕpAVtq%SB,U.2&`& [3XZ7\DP\FX[Ӽ[[}YMo (gڠ>~I}^}Yym]O6XŨj֫JpRK8ɛNZqV'<;5{Y%x  <@zݎ 4$ظxرǪ#. Sx`9kSltXξN7OUFGƳ:xl5Ql㢎1F뿬vXӃDzzƱ[Q?m endstream endobj 81 0 obj <> stream x}iWSYn;|_҇ @B7aeg7 QPDE6h) eW(Neι}χc1ivv~3PaYO\s~i0o$gDH6\$d7دcM0`\ʚ 2l?\?o 2%H翸ٯA )kA h̓L\`9.A`|}9`|sOe ? 1mf꽇 {I ǑP8~ K^Yl1{mve6DEO6@=%H` ut8 ,BPY;oT1XJt;dosqkڨPONGv?=})~ O}s=ku\FFzIIKcNg t4 Am +AY}_Ah7ɍcSq3r Bhk)Hq CY?cn0ލ8R"mKuxF?DJY?g͉/ N[f7W/]\?ږ f0]> AZHc+@s/~('f7H|a|RHeudߌYSя|*ыXR}`/@IVؘ>?7e1CSZ!񋺹~$GפC lq1.&PBm"oSAxT}DHr@eM캤/ 'vdytv`liv,%Vy ugf]!Sڍ_z-B[`*BU0!}k!}Y$Db!\6QYE]bnWp3R7vyB/!goƼp I!fzN{gضmYN!3[&;p@/RCHHdUoqO[*A&cy/?P$ 4n|p1+aNx Mv8I^s|y$#` fKpg-#LcFn ＄40|9lw.ee><"E@=ߤ9!OB\ dLa;NeTb0@qiϗ&;$ ŝ=8WFd?-f-<4~e@_d_(ǣ,Ѧ yd:{HH;ЍD df|:0R|?;oqwdq%Y4! ~}!⎫iw nH6̥D/Mv*@wBTP;a\{H8 :h:=SdCtG~R faU:HcfMwL9 ""Mv`u{`l}O%jqN>S~c/Nc:oHDyؽ^-\O52inLnгء? bap$Mvnӓ4[HeuSXd!pdi\'7E؂4!`wGNv*M iCf03 còREͧ/MvH3P{K# ˴R&;5㘏 0qdt{9WIlq?{؋tLnؤT0}QiC&;舻EL S2>d<4;f-bzrxiCvs+ Ulj3їy<0x4Wd8ѡߍ\ e']gsNެy?/Mv&}g:uyl1OJ :04?Cͷԃ_\~H7W_[w`_4R&;ĉ)? ׁ )5:,0WQͭ%  bFt *Z :ya&; cDs["^j,]}+US;+T-,~Ig7.lbĬ(}v&%}sJJwaS0}Iutb񚾾N<>JV춗i'a_YK{KI!CDnJ"qs=oq.rCvr.v4iòR+F~qC]p5?dqؠ~M>%1e!E=Wl61Hw˓dh)b^ZX_dݦ2.9?uE< ]sI_ N<]V*r,W>zoɝm>3-jהHt_%}DIE٤G+)$).ku&;렑wq2>q#uB5n XdGUkuAAO/Od/ فoq7#œuU]:3B- D;aRmgtꞋUՑ FZ1[KVy ԗ&;vW`pcV$}=uυl՗1kJt;~e|39[?9LeB<}EUWe4_7 Ax-n9h#W49F4.DV$}D㴫d8OSB 20|9<S,C\_0z:oQwEy t2.gZ)-;(]pB̠]:~e"}T9SS+Rw*ME >"';\~Kd';{Iߩ%.?t5xөYj/`۱3,.\&- F@L& 5[+5a{{mVQdaw!#qVlW4_j訒dFfi h[7Ut(L t0ZSK\~H5򯭧eGgiT@+=r }@R< *NX2LVC$]հ}I1Nԩ7rOD?,M}IɆbS^p}]|ܭ3k;rP\pP^V|0bd5|O\.L&-.-֔diWK%]5pwV~)H bғ#*-L\#VVlO!lJ8eOcPGWFT`OY^ U;$:Kd2YUIs!ܗT~]bRw';X惉~&>xQVh]} Rd蔾o;FR`)*idO?uWke"̨;q9Eq\Jhpy[1f:ˌeډ7}o>Bcfb2#zj4""P5#5 L& !RLf):Ob[0^}O^n,Nhj ;%.QZkj2E{U*SZ &7a-&د fc#* Ś+ )kVZ(qR|Q'.ؿ Y+5~W\Lq= tj9ۧIrr,}mj+<W0 '7haٙ>9>"H3"#5jb?5Ny2Y+y勘-U4*\&4ueFXQ*y‡0؂ҒNn=EOnBY`ct8+uKϏїw*6w.D/$h++3"xl,3wF>h)R)TʼFK}FKQ> |Y.5KE{Z6bf):s3/SחTFW0eMW\o)# 1 YNS+OS_s \gJJhAV 0urC[GمQU-2P_X~ЩWvDW$͵ko@O+Qq!}-|3}z,̨,EGm4jLa_"S+?7✜WiôX.-fL3$S?dw /'w n;W3}H*3lW}#*yڱ/l|d#e嫮3K`} ޭo[LBG&vW%˶%C¨ k_\~H^heս}YyXȻtmxjoR.Ƨ]q{jzItGw/ۖЅFJUӾ΃nxjz_ RzVqꆭ:Ԝx ؑt-ÿ8uy֩x)h`^$ &PLuI N ]n՚7+ ~rD6􂻗y.6C#  FM]D:g ?#hwMg5uErGR(R_Z&Y \#50`=v}rC0{ )炅CL#u+.Z0/^KmҶhx]깻BLjl3_j.hrqW߸ӷxNUjB.'.<7/.?$} L&khRH\jt;}g<"oqɎ~} .@S`j[[GYجQ偒JbǸh}-P19#)sJyo9Z\ݽ]Hqi8r EC2d2Yg%gZZK###`PGJ@Zݑ*)ՇOGhk^+P~6ԩw5ܬU*÷9$ DdZ7O0edAsZ)؟+`~8>ve[eQ&] Y WHqu!D2Nx12 J ]hdvco|ˎOo/;j Kuv?E!޴t*=B'/|:yþrmIVa@e}"u0ϻ[ 5hqF^AZջrUk@yUCR8!) sHq 4G̥H/χQ3[vuڗd.,жm껾ZZ$} O/0ۀ7,XX&P7PGZOD3Xc *ֹOՍ]mu.44"e(Ψ).}l{2́z%xy1wЋSLuՠ;r$VZ./PVJ";kJ t0jk<زט7NEq̔qLLZA RyU+g0xnB+P_4 Ekz$N'@# ׭SSvFҝ0q1܎xw-s-.U*(3wԫ[KmWq8t"mgk+0Fqqn*6?DA<s ԀKkŽWSmo Wk%GK 2`E1D Orp?~^eRA(y-Q -lWUZN6%Q(rur컸n/;JJѰ-DZr])񈫢꽰PSYek(.sBSCmZ,7̄KgA:"wn'O@FXzyyg&kQTy{Rrdvei~IXRr$ =g>\T}8ڇ.u"Q ԪÔ/ӻB|觨^6xd*nl2¨-f{dd3]9ЭK5EBD^x>0Td3NAV3l{nmNl 4]G5Jyn 7kVj UFSs<ur!QYˠVEݴP\]wTJG}(谧z鶧cWKi-lā3'Ȧgģ>gs9Z^b`'lzfJ{9r9 zgɘUjc(+;Z\dIl9IU.R,#j#z3ie!>1jIA+.EǾqBVk_U:V"%T)y\HrGR*9ʋ=j842I͹wXǓwvv M{GYYm3(eC #%h#MP%eo4 q c? nuMlS4di-o]Fˋr+E5aq]rBPkeMng|虽ȟA^gYiOQ|׶˵v D[k\.U=hnr۩׫R v{FM٬1|*B5ðV5[WǠm3?q4Z"(z `W5=~'ZGIJ{{i.-r\$t-r}zHXS[k/9+$*ť:ekݤ'Ё2N_\S+'iۋ/l=XGr#,_N(ZFL{#X,?wvW6EА0`Ggl 9}JfFy*q۫JA5ʨaBg*dP*̅J!R\(CjㅧQ)zj/P-5Yl>7)'30X,IAV儵)+$'[|wXϑ@rn[4⦉G!@M aRֳ]5鶘.XVSRTfYgPOl|ԏ4Uholda>d@Ei`~z;Úkn,.^hnF8m2YbD+(RW׶ [ "!}n%}B7 X j M=H"h4Uzs0U$G؂HA`}#@02/)f;=&mCqDFKa&ʋ}W|Tʨt4oP_ a 0pU?+/hJ<0ؕE5IhW+M-:qV+3A\?a X1T ";S_'P_F9f.j.,))H(@vy*;kJ,Uٸr%h񄒪o;IZ~H65Rml+.6"~%'da&HV.0[$\}kvb*-3a*{˳kSVБL a$ïOJ:ݡWV ܈>}uLEY7h|TڽOәqK M<}^QꓸGEuDzUkh(*@ ( g;ClWtz@Yii>bBqZ jP *mŸē|!}-Vؕ4iĠ}S$gx&駨NlTd6궝+?ufXUyHy;NP[s% $ǧm6'|r;Rm.-rڠQ37vV,c~0NEj~߳A_#c6TĽ3Q^_w?.\OF۷M~zBjϫ׬qJo-+cy6_:. ߎӛܒ[Y"cf~ㆆRŨ/8vT\)FZ}NL)` c(C6\yC8@LC8vD_WU78РU*eúBm{I0 ÑT0&h'x]u>:)`L56Tʰh d$~hxwMoL;Qq*dt*ϓ’`(+D_Sp881F}#]fQs̰ 9ԤU*] \&?gaFGN"d.Aӛ@rͽ0?Fg^_Kwb(/þxxώrK=OgάѡX`/$2uWs߅%[Zt*OUygd XQʢ/ ^Oe(?cG4!G vJ9F4$Fm, X0_ 4,n$kj\io)" YP}gg翗 VLb[ט_6gm st eF]1z?jp ->M}1lLy>McG նӦnd^>8RVV^vdWBB@wRV0ɕHV,~F|ug 5.YAkA]g篵9{<{wP_9O=ƿ,lK$sp/pK7YpAp+)G\<̺ ì9]_U١6ITt#ؠ)vdZ$7N~24t:̣jԊƾ2YZ ?s+ Jeխd¾8s%|Yla0Z )A%Uo4>mBsgy?vð /W@_IIRKpyw`_K쪉(J<ւ$GIGP.+AO$쒉$$?Wj ڻa_BzZp(OjB?nE,:&4G["?PIrJ\QnO^HUA!QԳEwɷ`_"$ڙbL\d0rIpׂRiE$ LAjwk7ZP/W&ݼ/)?T؅sxgfZPa?ʔs˿'c4ax}^OgɰůcD9nARV \oR¾q)KAd}mjk[ZqoP:_l`䶵W>`jt_ٰykA#oxR1ٵ?+u/# GMZXmkAPUP7&O9~HNOToR @\(t #'f7H}++Q>߆N9v C1197'ǀЄxdz?&2oKUAc8䳚C?&STAHւقmD+wyL9م$gn6%Md-RԷkRf~r:%kƿ?dpj/m6e:۱1>j,q_4:uv>;|r Vzj]+ b|.GӸW!f~jn`_ k_T0ᑊ0(#栈kZp}pPaBQx< ؕ[0Jւ'x<_\˕ݕK٠x>K.Gְ(Kak4a9~"L"Xt$k4sYo`% @e7^H|@w%kA w\l t0?(jW->hgqmb?$UG ,!ȂCyq ySG]p<N_l [ ~}Ԅ j*Kk !>K ?MsNk$kA q(2K(l0Hop:9;&!$r߻!hB`Z3gJMM 8|߂($kA  +FoϏ!#!ò_dXA?=&kZwFB.`mtt?qL.}䯴zZPEQ=_)> \qr=M aմ4vs pp rA*d]}n᪻|&n| Op с5n)Ea{ZPB CBA޴3@_$kA ӹ]x?àe7Yȿ]2픀쀠ә9[porxHyxkA!KӉ<ϓB| Ym9ϛue4vy}Jϖ"шܳo?ojӳ.iuJG EqRUPhW"ǾLF:k_Z TPZ EAɮ~aL su$K)!ZZ?tvwX Ma $HHEJr\;|s jaaggLZpd-(!'WmEIĝ};mXPYIւPxHR1f}[KIւ;,'qvAx,KIү{ E}=ojZ۷, ى5u37yQpkRs{% BEAĮ[i ,ť,%H^xAZPxږÄ(d-(ABUj? 5z #rp? يϼ1d-(ABʀW5)/Yd-(Zbs endstream endobj 82 0 obj <> stream xݝytŝG6c/v9 X6!$!q汉w!!&1 @ W6GHNx,oMhFFcit4F͌}svUWuM#>$Bl6KYubk/Y[[}ʩ7=+َ.ZsIF_Q!v ^5E_Up@Џ>t̸`beGǤ~^:̻F8fúGK K~оauZgUN5,-_6bMMJus%w~fRtV:l8stfÒtWmj \*%-pwC> Ǫֆ%si;aJR< %cمNXx%8| +5skANߗUΆMZ gQKAޣE8 ϝpӰ|K ̝>AϳaE8 ʝnj߰dr'0OhX2Q` t}%ʷ;VJ tVJ ^Ϩ +~d# ~ ݔ4,JRwݐ%CpXN-w$aTÒ)[NXz#:5,JwJ +z w—ْ5;2^AQN`l`xJnb5ٝ'f ԡXMu',]tBd<ܔ@8Wn<뿚rgD}TM&X'ϣ?d^CpN#|gW7p֝Lx'u=.qM@C* 厏~qŁqyA'0 ْ5;g]rg$}ʺCrHwc99YjoF˜CN%N GDoG?=EH *e3hUΑSެ_uv'GN9Xa86U+5r{(l>GF" R9^m:{*K Lo/6Ÿ ^Nrǧ2JC<ț#G#$Guq';wQ uVqSC$I FV7Ckxc90A;<ϝck^juǝSlrUfN=9Z94?LN8* (ôGC^wc׹">G ?K.wzD;x*9LbhIBwkcl*/}&4`t 去3\i&@q[Ps8N`]SYHdvt# m\ N}>FX#Hr8E%LP 4(70>iN`-wܙOkW)|,1 &wzD5ui= YrW.P˧joQK0آ I0;u=Zܝ#/19$/QݝZO>%)hFFCPs';>NXz1'X)KOCAw_CY\+u%.AlBsGMS&HZfN`]H- ʍ#x6f&F JfwE췇`Zg3w!MrG7ETkC83E5Ra$ƼLpyu ֝:A{S1n`u fAXS{ad)#Jw"y&PcuEQWU.as'0)zW3zBٷ5hQDyaXcm>G NXΔbJC֧ZCxaVK Gs>8ҏ6!Cq'r&Do"χ) F&Iv.=1CPa$,AH1ROQZiP~XHa"1Dy#RkJ^HNb }]|K;0/5Q:(婄'P- i_ ߭7E o$eݭb' +)gkm yf`#g30ͪ|!ޢs' )eut pgY8u{b0S-8wA: 2 nM<}2hދq'GDGWJO儶@/X榯)屝'כ #P8aDdl4ƾ[/GMpl`uL˩!ܴ8=#+B@|zKu'(W*KyZ;ۤ|oy&{N*}mx u<?Yaܤ6MF366a\(Eiwfi?sCNܖ aC s=ICzF~tDLOmpfS#5xC85KfDypQ1sU9q;T&jz=nWEza qxoJZ.@3sAK>Q8{vH[z;޶ _ l*]c7%-OC) Q!)"t@Ck {cAA47vTq$}Hޔ<%#b_(%HU3n($k(8[t62w>+"AA4֚$T"-O#|Ͱ+ް(P9umFۇF=[໏w: >~)y< IN't)^nb+HS ؐs, q8]# E`8cXPSH$ "QGq w&"Fk FAL;OiB^"WM0)m$l Js&Aeb;xoJagܕBMOurDT&YQ-*b™2/_:#3*dwJ]#q|Xl g`MDO|R8#bB|Fl 4͉M$yua)&[_~ZO^D+FrHgM3XpJ]Kp)WHv9a*ۃÇm'LQe)8y(tҧm`8إ!W]Ti`MCo>)/*‘ʲ1ΖGvhnb([? ;蟆se NV˄0?Bf+ )y#-lLlPxFJf QJS)eIw '޶ ;.91H'p蓔3IyR] <ҘCa!PPK1-O .Wim qsU T&wb]ǐ<=<Pg*8+ŸOCÔ'reX4&[x\htv<䑇k3#Sp-s)'>JuW|raO~v%:}) 'QUrw ҴJKmFJQ8C`  OP}(2DOS{9d`Mт7-s e FeJ31<jm3Xӄ`|rfёMNW&!-+VڲZa&`gmP88 _U0l;5R*Kst=UD3b'.a׹ʝtԧ*٫|U81.l>-qgH૆5G[Sfr}q&%YBN_,~CWh0Obj6sIlVlTDy5q!E=jaRllY}qA>{yOkVf[Y"YG rȰ(q5*W̡Ͷ>n}ܣ'Ni`}O}[6cӧ*n@h`MOᏪOc}A/is,:Lx~tO䋘}:qTņ(Gg<7gfm(u}JN/Ɏ7Î ,fu jGzvduƐuzDt/Vۚiw BPBXϯ?1M*T\x}yلspqN:GM,n>̵OdqQt >NÏU&:Y\,1>f-PwCVE%&+AZg{8(|xk^ɸZGd ԧ cBb1n7>a3yf::sRTEL[FlK"e$}ZL _V Rf;nrRDgcc`_x6Vlb?a'8usnΡGђ )L7kչalدnFm=j9WscֽY}aJ:,>[Z^ktԱV3&\hp&. 6|=ܬf(OO<]WXVXe)i8 :?+a་Y\`OMp S| A1 1ENn!x>S|%HucYDS671-Ni'i:ĭ!5_geVsYݸ}~[y妢"mzm@Y Hd)>E:Id)>Em `K$ L)eE,>0ŧ@J`Tam!] @ 9}'|%2,)=iLUց+>E<Ca#}e "Ibb" \) s9*0_\cg0hv" }V4?h כ`L\)pTZc@_ѮU,>xh]u,>pŧ)@㨴2uu8io" wzc0xՉ,>EhV' k c-vG+>oѣB$K+Y\`OEr+;* ,T$!}0xG%d`" lH!Qw,ź@FZs)Hh5FTX[]d`!' P^kyMa'JwjS6SĖU0 k Q.Bo6Bb üHdq2|x~>fFu,>ŧ$|3P)S|z_N&ҘTam!ɼݛ37\. 7uٹ?TWg%H^RuI_"d)fW"l]ȼLdq!n&oM%Y*xq`3i]*>6pJ|KYω,jz~'t쩙.K(sj?Ys~*4R9O.Lº@XIIdϙ|YId?t endstream endobj 83 0 obj <> stream x{WS@Cݾ{jI""O2O xU+x@S)SVvY*| HYYxݞ6eeE ժKZwRQZR 鲲'))0=؉'?"Zt=֏T%Y#P$`W'T@:bPQ++{M l¯IE}jL ^\o^)*TbQSeeʮHlY/U-h^?(T4cXӪI"TNkuS& P\?OŶ{Y*͢+i~c/nwelBZ /uI ebcwdYٗU`nw}]R P<:]M*t 7S :`S݄̔^(HoT/BjRa_'lUMH/obS`p 4Kfee]fdzJGSgyQ7uH!`F*?::4#Ӽ HEPZL$yGq=>R t@ËtYYsG4( #ӴLQˮ|4=5 PU{4%)*st) Ӥ@(~$h:0J #&'0Z_@fbMjM2i rBE=(Ū&*e`_RePZa/ѓ E,B=J1*A ̂UnjL!cTl/M WVIyՃd4)adU>펀UDZ_0_d#@ N~PB\._2> R`,ROR lYYޏ(r&eNO/&%X 0BM QqZe05 @Kυy_:ʿui~ZeGc͓\&Hdya(@&(QhЧSI,+"PH\ 423%s.Ɖk}@FS!VƈN*YOWV@/єĮ2xάOU Y ?('y3riI= o9@ ( qyy/Ve֗Tſ; ONIH까wI\A"= l#;AxV+> |F`UH8D0%JsHO ^L#SH Y*AF*@$oUI).`a6 4~e_UEP%@xOb-`^^f=v)^̲ C{5&O@UzͤdƟSU tVv"|$9z*(6tLJ5)ǎ@iԤ&x)%Mƛ'e2}5jUk})*mTaC(] MFk}zu9m8a 3x'Jq!֗J0LJ%(20z&yk}zyY#W, @ߝAS~q:X1dW%/0$ǃ'y6N$i.(-OU KDS*UkZ_RR+B&ɠ2E@uIM4z,` ;L_zdkc3%N 0ɛJAW>M]8j<@q2& <ᓵg\Ky] HJj}zsހU4:@KH h*RM_ @q7Z*r?_b7,rPk7VL밌NU s$Yz#(:'y7SӶ. .~ ?ь2~/[1ke@%YWM?A$ʦk}.S d)')!;֧iU-k*H ٪iX(x]*V* SBgSI/n5bUjȉh@ =Y%Qv^ sq"MC0ʣ;y+KLj})*[{0j: H@As7>m,7HAĥ0:?ˠ)%^*ߵ5-ZW@1L 4s6G$Ve D^ Fp,5WaD3/Zu`3ɛZUI`@?o7 $֗B٨tI*P&yi:$oj}Ve$GXv "L soI^@OɬIj}IOU\/QܤHEx&:+%9I֧)C jRAP~-0e/| O4C`Zީ})&yI"?"dCT D+T4V^^bfd(C0Mddk}u@D$oJ*Z_**@A`*BjAI^4KF|w'NIª%No`5 IhZdn6wOT5l`UIJNR!tu)o+Z_2Ōg巐+'(s8xrK>I_*Z_Rm` qRO֧s**g)>嘓Tq̒%HȑzD]e>3`U\ (baŧI*8D*8Uy$$o4P@-a"%S J@bj}V5.jĪ-\쌊( y?ڰ]:#\0޵lt@99-A9aI "yȧ%p\Âdxno(BAP(DܴDMI4$ o|/`֧)C Sk3<7u@on'L*Sc,"TSb'yj}2Ȋo|ϺcvJ.}}y\8$n"@/J!E-"-ZU}alWf6?cWClL/^;H@Qr$o45@TY21| [Ģv^eϡ֧mUgtBHoЀ_"@/'VORR4ˌ~@:N闅͑)k9UAYx UA/n` HF77 1PKoUF@d@0i,'*މ^eL*V&Q~fa!$CϨUOEn$^ lVyI?KJS+VHK O7|yj}d4D8ٿ"xڊSaN?KQ"D" }O%f QZ>>Ve0Df&Ŗ-[l6[ԧʭX'vIj"80/1:)o7 pDHc?OY+>%.iܳ4wBHI7 +<<y-?xPzѶmGnl .m))CHI7 lh%"q2˾8@}nR .u[)4pBH; KLHwD燵5F!Tt4#+bR3 %@$/r$C 8X*Xz<!Q]b/&0.gs'XyE>P%jB!Q'y$/r_/0~R !FH8MjntUmkXVxNef\2 EI/؁'y֗'H:DaBɎQVj[kdK-Ī D8u*2B/z3l̪ 8nDQ"0)jv54W/?Aj[vCHѰв(!)+pʫ*<$ݲn&*sH+6@E)Ť$Z12LQAت R}H?#hzW]u2psE[ s) &HK2ɻ2A&(-ݯ q yk~SW[k8UF>&RX*8U(KqZ k*dd0Zt!X?KWJ=5 W^UF,%!lVbx>4HsP3FC 2@~[Em'a\uDodxly@̏jpa%p(spjR"*583Hi2 Zş?AQrl:0$*k+M JrXBI4gݤku|+5Ƨ?"lU25rQ3LU|iz⩜q[U*s_ZEJ,H1%s-RZm);֞hA J/Wa"7ǏK>ߊϗTrootl?L e2)}s-&n74U+?fji X%h>P]Mg UǏ?FɳQYъf^dXb 熯,Xo1f8[*k]Ƞd2V)u~1aǚʧ-;g"dmN ހ P$̸L. $7߮VI2(^]P{ƛR]}5Cz?AKLG5[cʠ^oϱ5&׃Y=nNr`UկAw0t^pkB30:b[uc! .=c\V7"7| DΏ=Pv*WFa=~m&&u\f=*j*`$G+9 EVEg!_ə^v$XiHbΊ8|'/xg]7/)ՊI3w>=eYC T AY6<8He5dyKQ)[߻nz.w,fa 'ޟ\52!xGZ?FHz`QI$4bUItE/,fYYݿVǐ]]vu=ˠDIgWev"b+D~= $T',g5VF}ğ MM)`A VEt2̾}v[ő?A 0,r~AA%/0cTP P"nΰk"G8-ğ MM)Y~xh[qٌwwm־mˠDΐ~ JnrcT@&1~75V_^;XY22d`#zflJDZ}}^qd 2HC2VԏM!ū5& Uyw&4e8GlġeCh ܗ;==X$+iލ_43!xQSA0)+^GeD ҔbĪM5DW$U?AiSaοezB=I?}-#+sE3)QYe۹3k`WȲ²P.>z[i6>.V0t4*&r=}Leo r5V3}U*k(G/_DH5 EN+,.Rja@ğҥ.m7,J2 pv|hF~}DZwB Ҕe#%N'F ܐ~sUo#.Ur_x%pLgd X yH~W ʤ2bew'NCEȑJ{-ğإ*ZӧX><`\gWwOj5V=&dhXv9/o9n!^?ʁj{uն Gzщٴ)š9~1e! j}tf.z*GwR: e<NJUj2 كQz%pҖTf Ve2=5g7VlVAunn:8SS=u/c2g|ϡ},/S:Jk"|l/;?A21n_轙R&E"+O;== {̻ ʛkpj?yȻrw9|bU96L<C Яg;m6p;t8{3R;b&V?c=۷[6bZlyO_@Q(SU}j".>/ ~y&[?CЉsUS9M^& fGV|㒏w"Czk{';;-b9r랞Z[8fع4aYNƑ)'x%:A9>FBŪtM? N٬g!.=4X~k+#N YbE &hӑRuuھ=;:Vkg]ainz.w7Kil˦IMIeW.pTFCܸLdc5@D:{a^qg7vI-n*ԍWJBM{DxB4vG+f[*+-K`߾?z7lj{VVM L.Wfry+ɡIRٓ_PQO_ll4#?L33x}]ӹn:ӻr{|M;jv] Qdͪ:>hIx)X,ƴٿub [ZE#L}춊#w7(ˍJu[&R3}||-|hxQI1^ܚc|ofPEȧvMH4-iUeDgߺG.y<5v{Ӥ6wgZX,N烃ctf i\U5k~Q"=!RcTB1JX?Tt[鴹4dtMċL~2,مT2mzeY,7v>5{VZ^~C dtvtXۦfz,˨Vk&2/=F3& H㊟iQ652U_X][`k"{Uí[?ދ@&֎QkK̆.}' f &W:kk|yh⬨~Eh㉎_~~$HQZ^T/V+lU1js/r~==F_,fk"o髪UmJsc=#]{)8}r2tYVOpI;+lV뇏[, iW}O6c̤6tB5&}ET^hN &iW ʰ̵7zβLӗijX,.jG:kk-K'HQKb-j[E# nj[*;4.uZ^ΩuUώB}s[tXװBQYYYbl2}&i6st4ֽ / =΄t.1 'ҴSUZ ;ljknٽb޿nZ],,{-KW̶guU]uU2ڈInh;T VIt^Fz_Q9~Dbk 5lVG_ޮ̖)&0o9P03~YQ,Z^~*fgepǎdr'# U*n/G殺灁*GKWݤ@چҝNL1*H$l";,WH0nEu[{Uk;,1{qa ޱ_ݽKϭδ y[[SF),.-awVs])ܼt7Ꝏu(I6n2Ň9~u0B]Ǻ[0)]wV<`o|%fai:d"ΨUU禨nȃC,KSuբǓx])<`UR+,~EhiFR܌.Q2}G8=#yyʶKf{M+{${SM.Ū.6yk"K̂HQ硫!ߺZ^,'*ouU@J,?km嚛ku$Ʃpw λ\mm+$6`$܌.NgBxpP*a];mͮUO/I5%YFmT)&Ej{*Dy .Yu̱k`6=xYQqg5ކwc޽zg]]ÑМZxWWmk w.t|Rrzm!FDP C8UKتk\R&Be|RﳿLfI_:nÇVk.YQe.-K3ꉙ#;-YQQ力ZxVj-S ET}I~CT ,tHۓE,}>zVe.{Doo^[H U]UPsĬc倖#UB4k@ԝbqo<`u=Z^~ana֬~ZlTrG̖BԚU5. Q+~nb#uR0g9gP=w6*.SՋqy\b7.mz4oߞ U\<`Ung74]!~:u*͖:tB+u1NxxiBܛ%P=Ol'mOζ +Di05%q;z<4xyp^'e2?fvu5:J)&.1o %X,ɌxpR 6Rwe01QQ hGǁZ[5Pks:F~:\TE)y8NdYѠU͍OQ*w?#n%U4()K憇W: zVSx`݅<)q.fBi۽[#1_c٭+F;|PCԾ}D{kqB%v7%K m&"Ǎ77멨ʌUit?yOɶ^wRvM%f; 롡aUxVCaikY1K-.nkyjM,ua|5ى:Z׸UYNRry^ Hl7xT[jC: |ʌRvaΒE`oNiʔK^ 0%`UfT^13tlR)&3>g]C,"tz*R 1Ҫ*#dZk)?eG:UYgeQiRM]XUaF!n^1UwiWB0ïRcxNM lRz"?+nNOO[l̟.w748փ[~bY/իTS]A\C͊U׳)R}s^f'.>e^ T*M}Ns{ UH1nNrdU?؛]~tQQ=hZV%`Emb``}=>+Ul'I,&HяsVgo.WkNo8ՁLMJ0Ǩ/)VEek^#e2Ԭ 5f^qw7 =z:,k @QM(*E0*rg'ZZvD]knX,R/1Ap,fEmm}j.!>{f.z¸U%K;{GQzsh+ya#˧XH16e[շZ]|XYb/ ]KBjM/<5 jGkSOtfpڡqoxRtkksvs^nd3ﮩs8юذ-C:{fg0Eom٬_w7#M%K"X)cTؤR**?U%ڶ|}?f1Ux*q Q[WgX$TM]m}*VksUնmN՘+o..ЕY/;4ߣ }DHB eɎ#eP٬])^콄"^bM*թJ /ˣGwضfwM Y4 w[,uWz8!u؎яt㝺l6Y[#6vY?>Dl*j#}o^W AO83t9ŪȪ~ _P+%f;cGn";RP"SOOxa\Oi*o-/rܲ;&ߪ-fRHF;:Uub?R|>BgȪ~>/lww(e! {-kdE'{[r!-yyzz:ֆfw7ذdWŢy}_㝝vsY9Umiq]eC;!ƋnJ%/Wb8e,3 @LSv5'٩P1¨&55я޹b Zx%Ϩ-zYp;7nkwumno&^Kܘ"!V!Ү)$VgGCۈ81n1j>-%f8X(?:ZoJΈ5^c5TVF--&l&p[{͆6mmjG~u ="7)"5&a5 ~XUaR p8*];lR/ٻs?J BɓOK`\Tiy M917VSݮ^E]XA݃IZ]/lݚe55qTUl悔+icT&6U @̬CvˣU4~#2f RDcftJ vDŴU˃jR*v|Y0v>K`t΄+|j2Sbf]:*+<;`R?ΰ3Lh曋5M>ф _&Ho`-QQʭ_e0MM)*R@nUTWTrjʩI=k%F(0"H랞m-lI[`-/I&cVtSS+C^@LQYe;sk.*ki"T&J={ھ`BˆިIJ=W)ҍ# &|{3əj{oKJ%E*}zyݻ}ڗ(|8CGVn~q">% އSI~޽cKLI K Paġ!-SР6uEfh:qoZTLA㸹ChV7p75dkbvM3CCCϗ տwiX!q2M- 1Ҳd<XI3ۨXb&7l%f"޽}[d]äKTtQM.2^}3k_muuM5ޚc1 e `z*H  aPo{(pN#~3 &Mֈ*I= ,,19[JP,]z#ki!2z󻀐 $VwRۚ]k^tJ4o2| Kr v W\~a/MG$Uh`H1>bp5V w#kbZXe eǛ74T'3# I,E Ց;*?km;k1_ͼN.F_~9꾲*P%Ǥ,e _,i5.LBwi⪲W9 ʡ-~%_B_vG" kH{·$oYkP4@Rb#E[`,x*f*fY)VEA1){GNR0 d y}fK롡eY|R`8Rs(2, dSIFV yГJ޾r!XWHlJd\x7&>L{bSü p%w:noILj'O%HZo50)7gXQת~1N^|}-apXYYw:I@ &"m f>`j?X`HNf?NŤ'יsHMMPЄԃ[|cUVA5'"$/"CH6blRG)HT A(RDSZnzz.6%w&%?-2r@)QDwF"~z NU I%&yozz[Z¥gUf&Wo9.̲aCb\ZB L---Oqc-qȫI%ēM d Đ>+!aAeYލFojI^ +d :=`dￏD"NJrhRkjI^ +(&eS]IOLZL H׮8%&/&y"VoU+GPC>-Y֚pzѵUԆI^ H56rW qz$o#*.?9!:J&yi<x<$)ևI7ϡ*rZ\/ }$%ϟCCxDRpG< `JSF#K<$ևMjaBjO<[]? bgUR}R &y|D??7 |?>VMS,=6;887VYI^ 3"׮ECUz }( ,^[ 9 88H{*&yq!]{ݪpJۤ&ya`n2fUi` #)^Wo4)+`((j ҧBKѬ$/ECCxR }FM &y#(#*?cZuZ~$/-^ YV~uI^&%lK sV'1*$/]d 8|!gZL.V6ygna.Bqӵr;@A/s&$$/S ѣV%fsY_@q#sč)*u__0 %GhRF%w_t`(WU~1nJQI^ oTWj{Dpt+!I掏?&SYyJVI^ (+jiZڢA"n(f^ #,Yf$/@e\WnԪ2p():ɫZ䄹 >/6:Iet!@Fc(XIiZLdD"NO I RGg0kR0 `^ɝ|U<|]N$/@%>}d+kQ @! rBwh>CaVi:Y<.Xʬ &yReQ] "d A~ʼnf0 (}O4Xʸea(m) ^>Ag=$m&y q"%{qNReee`(mƒzTng0 \,o>_ƍ0 4-jlv@R`0?AuEm|ڕwc׮]M &y A]n(x ik}X0 <$4ӾRovG"c`Aϡ`0="Mq*qChYuGHdE{ReժH[`F ik}IգGI^K]Rvttt.O{W'ye V`^Vrә1rLGd?wxfX&y@';cz@I*? ՚ڋa [aʪI^ULϡzeyY?L!of4)*zq?VFY=U 2#oKfH[d*͑AplZ߇I^ժH!$!I^$D>Wˋz`0 aB,X` aBjfH'`V>%)6$/E2Nv.=#=E"B!g &y\# >_xph2ƫ.cI^ `26KӒCC2ˮ[/(h:DQi ,+2*LENV%ҴN 6)`Y  $/@q?Lѵ0 h@ӿ$o)#u endstream endobj 84 0 obj <> stream xw`gJ(6Db+(3! ʢT;"Ḧ́PBS a}76O2.ZԉVSdd~ /e,~Qzƨ'o5L=9j{u:l}1qj,Y;bϣ'̟e;O4I\aޛ[kY2-3m*b~'!X+-nMxs6zEQ|xbAF؄ѧfGܹf[g%9 u2G 1zʳ:UE?DYW@4ʅaqG4fCᮦEUȺRa#6n4`TO<u7l+|B(7_24\=GsTe37MZ=T\LIPXUx͇܄,'T^8.BFA;W:xkry??>&- a ~#ߥ+~g{S O&~Uh!N΋;t%:&< ~X7e~/+¿rc`(7 'T_ oƁF9}ȟ[;/Ne 7:R2x3vXbDXӜߜTaWEߌ1 'HoV3:a:'nάȃqx-~b f-W'; F &w-7OTz fRQ'J&a_7N0Kރl<}mH֊>47Ce'w~soۋMgXʿ?gXJrrR-r!:5oZ3 @_4+obADŽ~s;le?^31ȑƍM,9o@a;v123Ƽ!lEV?&MhzCQqLShb&Y/~S3^wG` ?_.kI#P _l ǻ|8dC_`V'sgPJʟOx.NN@N -yjR7DQ0rS~S"<Ҥ C_S{j]/q~S=Eꔿ?b`Õ=<0by"1UOC9R6/]zκXڮgX~x7a>PĺLl,4MHفp[9ΩSu˗ow 7s?hP@Ty Twܜ pX";S \xzo+WQTt&^{qTGwQP{?k3ˡ}>u^n҃{NԲ5Mm/~m++[K-Y?Oqz1oqM*Yސz<~;?0,u$D^l9>ϼ^s>0˱Q{ߩHn>DaEtEȴ`q:Սo,$&n|ogDPJ)BNlkᄧPu9=DzE4Mɳ+j\Sy還͑qP鲸KY8M4O}Nr\^dÍQ p<& TDS4F1 v*6U](;](RTQmh- ߌFnO ߊ ʴjgR * z2ޕ(2rD)X*e nXb;~nq`6P;[w{+5>%Yf<Q-)BOq40 knu*߂hj}4=qt,}>ʉ'Zh߬tߚK}t+ }'jZhcUK 3lW8~G.+D8%TFwftRUT:=6nVBiÑ;8'1ޒދ@`9>0,8VO 8Cowe͕**RqkqĮ1 ho*}z7+!8:Uh_qH 6m B4*DѾ@K&5Ud%i8NOU!6^OG0Q`Dl3OuH,鲇J (EU' }Vw`WQ\!r A}ɳPUw=M}c~4"}ZG*YQ+?; u!ڧx"|][7+#}+:|>]#T*d(%cn ?>[,SX1c % n}P**͙;x+w\Y 3bY#U jbR80Ծ1CrC7YC(ŖډhHGPcbQD{qTU]_`S`;[UQӔ5YPU-|z%Y144&*B*l=o a;WUQ}cck BUac\nb-~;f ]01!S9WV$w8>NUm_8:F!T6uη}^-vZ@ 4=nTγpHU-?*R;v8va!Uߞ.|x]ȷ).SU@VXM$LLe),\*fO݃|U~~ֿJkdwYe =M  t&n5Z:-HU?[$=mĵLCYBqm/Q>+jjɍ5fnEO['+!{PU*<pkA tGzH:ג6\ SU(,A {ޛNY\cv@ RU1_qA״EÓwBKOe!U]kJ|b=dDwiٌXI;RUaB*{w4=ضPN4M=C*L>h?Ӥڅ4)NMg sU*,qye5!WWh@ɲq"4`fEڄf ?oC5 e(کA5Z?guBdŨe!׶iʁ2Y8k0UF3bq G1L;J6bH跚)MlF,bk98HUKFf1/"vlqhOŮqRUa@XC-M8ݮ}_ T{ 7$+c!T5h3:ۮ i2_~XUszdsRlW%mMיO66 Y 'l2˒29׮KW4kΆih ꊜSRU#r~N5DokQÿ5X qBUYX!&iWi$"#/Aݑ̧(>䅔'yR:]kpG2B0ap]S=CA-behdF,| &m-a{Fmh?MwpI2\B^1Om}lnW |D^#t6fldqV)ʿ]-2 !NR!̈Ÿ$YϷPUV̦R8F+ G2ø+ ]Ɛ咜S2U/vnB QUQgbܒLP?aؓ0}j@ EUQVlf%ܒsJdĐ]}mhma>/lZBvs/hGm3`4@n 5&&azbY$+*ު`j=+p h]i3bgܒLPU&YPXܮ~JQP;-ΆdIt+.LtbqNxvprk/EfX SBpI)FU1Y:pSMj UrŧmD2C^<\k7 v6( @ IW1{Ŗ( M+ω;B-0; jNCnnLآ7qsە$vMMV6_ᓚ\Ǭ((mwZ"4]MT͌u6JcXsI̝k0 _Ɂg=aU!kW\9 Ҽk:6̈E8,h5i.D=67χ/D֬LkWU񚏚l$=3bqUݪU% TG3˹(`D/Yk<Ԯ/tbk$)VeUlj$K=-䵩 ۑe@ֱ_w2a4}2% ҉ $l%v'+[@2΄1wBwon|z%N6&$T9XgCQ$ BlN( 2UzH_49PjM ozߟR_nhSTIWBRc7=)ိ[8cT#}gXZ/;2˪x.YQiګ$pNsJ lLVFz:\-SԶbɟWسM-a$ey]OHJBߐo4{%f"ؕli~Ķ̵Ҙ3\@TFYo,kCIzUQcJM (hqWnI)t6JFƹ[IO(m$ |俢/o9^!8ʼxv m0shR8`b;(vOV|*2 KLA cD9F-HĤSt,~DTs`rH^Hji^2/891-hF{[a\ y#Vz1/Dz *F8v0) ~Fld[F,٢6ʙH lOѻxUŭkϖ] yĺ̂6g0%Y"nFXh +x $ߐ k\}i :>^7΄sޖ)WHf&;%_>͗8UAQIvm72hW߮F):86 JIgqM{~fтl"ӛ_X@>Vyҟw$\YRq;{UВ6Bۖ . ];p$\YE%z6J@,HکqFCUZ2nF-0~>m>_!LelB3̓8u9-,HM8.QUp1Y-#1bu !㋜D9~ M$:S8.QU9 3#{Ќ{p_${`Ϸ͏s &̰ի(Oȓ΢CȂKTr3bex` 3 h p\I"LpRs1A+>T[ ud&㭽 v $dg&n@Mٴŋ9tib@98z>+iBLLb\L3u[O6|OWfIEt6 -Jeq@txh$).QU;̈Mzgs309J2uswּs_[( `!Uqp5 %`ћS ZҜvE|902%:fP9ΟŤ0)DM:[T:϶Ĵe5<)`.vw_=L!%& R_ڎde8E2YXr׊h ʸf9mhT||eR 'sk54#- IWr[N[1;|')8(:l 7c筩6"- o.eL\W(YWͭ%Xnod8y[ J5  @iݖVeÎr{ !QUKgVo˰785!>lx`m΢x"aV$1LVf6l˰և(6Urlju 98&UEde(-2?;RCNgCnRU'\2ʶmFbMA]>w`=[RUZmܖaLԱ!QU(&+Kc`_9R#>{3 kT Ҧٽ-w6C'k*U{Ig[6e9VM :-4Y8~,@ esI+ vb[ g:juhEz!2]8(YɃ5r:#,tKt#U)t·>0/ y I=PՃA ](i>֗LpC_ MqIOR7yU/@c]\Lx^xSoShzk} @SWczA@;YjtZM>`&s Iܞu8H8B$2rWOBB̆bm}moI-ڧ!tby{vmwn.&ڹ.ڧ!a!iT`_$=}6>hR輪"mNJJlpgO)tZU|@>6mp]C 9z#u jcj&W}rHTi3ۘC7 z/`@:':X>6ԩ;3kg0v㮮68?:C#:wwH%ڑ{1{GG:tk8& Xm.nD@tl$YVeܭU"'`.%:- Nr hVUELz{} d^&\} %6*)ڧ =-IE .%hifztCrvAmRUͤiE\orp4g0)@mQU,G.yLUhUw)4h [? whJjUQmI/:>S)(Fd<`N hJU:h#Sk!*5>JBV*mG@Txr{!=&sa hRh}N! 1p!*>! KƈQG@Ux hIa'wdD@sŮ"<}2IFf|' >9U vhIhz=)>9д]=f hɵCi3sሜhBhV f hɣg|1)@MQUcN|Ww̅#} @Tn>jm.BCޜawf/Gr?i%FhpԊP1'U K$Fh$9ÎQ#W=߄c.,Sߜ3G@RA8>cc1vn h/c.SRU,cǨ0NYp̅#} @1v~ hMx͠*^4tȎ(^U?FwOӸR@1ĈjB 1*ܣ}$e+1#& }rH{*b¢5ThhRYUQ#y!sah8BQUQ#TN6!T #$GR @1(!TFDHc.QS) cTEdpKM,sሲhR`Uŷ^DEH*rF8m> a>[9,;*} @uUhhL=]k2ڧ-RB"0GRC4,GyZn>B4F="0GRwvF6QS*\QT[v^l()MT1*R}$#} @b4[S|W>*cT$Gԉ{|GxZH+1* ڷ68pѾTYS~#tzh *cTDQB8ѾR A DGCT@m$W1 /.AK !dh_)z_5+E~D{.R)!h_)z;W=j8]R^إ4W,bK}!4W<-9]M?/^ endstream endobj 85 0 obj <> stream xn7.P%0 ؖe"ho7 P4I:@d[ZG4ådH ϙچ/gٮ}`n?L>Oжw6|y;'qyէo_×h39w_ޙӓL3gg˅;]5\W\omά|Õ]7xzzr~{_7o3,0=3ggfnɬ1>w7] }277&ι9zԹaks7upŌG3Jn؟.o3 ͻFg1]~iO|UŇWfdhcXne`d}a}Z'S\iXC'ݡk$G%5#cyj.a&\1oy .@僡("T+* DUj &@諠AC`ԡL9}{;* $b$vQMwwtPD3pI#6@Nn F  B|~Bua =P*R8\9Nt"6=i6D{ (r4YgGB " -dw* V`^t80ȻDkp ?lb!_ഩЂSd{qZn*R+*G 9XA="-`/eN<=2Iݾn \*& 3Q1&"E:"! Zp- ;0P#FD ";Vbxb(xr=ZQp⫗AGQYq)(\ +EJESA)p{ n1f+⦃6(~jb4%|@Wr3xQ>m&ɀ:W<8wFy!*8`VlbVD47U:DE2ș蝨Բ}Ub}SoHs+&d)rMf#Eq噈=RW5њCVs!'XGJК[PZ j\ȁ )ehUD\%Nk:(*֐qQK9\51r/4u pQ}X +'QƂU"z iA*nrDD(.MfC)zijDObnVE_:.%jJWK l#kY v RIrdn=*>gK wn@Go}jR;#q?b'>RAJIq^syꈟ,~'C:}kjO96] n/ŪKyPul>ޫ?k: @ _J([$H}Ky>'5QbO/(椭BD/ 0EgYL`>CԸ(, 3.r|*j8&ΊYRq@YMԠ)AT;A٧wXp dO) TNc*4SI=ozwO-|PISu> z]IelU,5ѭruV#hEZ>1XZ0)?RNrԾ2$ѿ 1Z:Dbתe媢.|Q>ywtD].w>Ƹ5V#}n6' DljJ|" `uLN;jݎU"SK#!@Ck-Άf%B^,.vOk /n(V߮Bu5~מCg#Mlﻮ7)76oLx- Xc+>4wq ٯl9QRkrmjk, 5~Ws|P: endstream endobj 87 0 obj <> stream xoG7ː%΅bՅӣxY O,py}+W"=zH!<}"$tRpӕ܉I 8 |@x)j kNtrMN){kC(}Qv52<4'4G[":}HN١EVDa<"tyZQ;g#މ([Y$(;k6]ǵBhIGtʮ6*JM')=k6zuPB4J$0ifHV$0aIܮ"\uh":$ЎU~l\" 븖$tr|.SBHjZNh-Iy"Ē4_?l4b8nyc-I4(%i $w]R*H]ǵ<ْ4wbJa,AV@/?%$="R4x|:3aIT6K.D(lo HDĽdIܤeLA" f#rK~>KZ#ME.UHwމXV K)JJp݅J[ˤDHg’ĸ%iX@DpGÒ4wK |ܒDoI/)Byc-nX-Iu–<;| J[}cI)tW@JDBi/V+U4/|$1$SEPZ$KfI/F$o/,p:WKoI/ =O!Hvz$j$&6\Uv>fHB@"%RP8L:sKrUVXD羯(6ﯠD`<$¦Ȓ"d\Dʖs^ 2#U] &,Iv,IePyq?Θ4նcnk+J0XvD6Zqr 0^n˸>bߕ$͗4M/dv)"Pxӡ &IegGC[U+,WXU@'Η,I Fj*RxB(X\a%QCfK6`%N4ԖPaHE8_28xŒDvčv蛎^$6`Irm'U禳-$F$apUmnI$h(MJ\}+ڒJT"mo%[BБǟ~KV"$`I*Z"88 w%XJGD0(|-Yz=$a)Tft]XE73$Uٌ67)2#݆[LvD`I*9:^NSnP$=W!GB`li#<T9(M9 !M1$R$U @2X__CkI$NB"{H# KcJO8@%iRn<+BN}?ZHni,IA쬀iѫˑ$w%LH*{j4^m,=Ө"r$kI"ؒdsiAi\r~9o(-Ip"-#5rM̊dN6rlƾ/c"\$iS,Iˌ}Q˹JS-I{= K34%i67uW]6;h$^s*S/]򖺄y ZpiQeDrIp5m`IfcVYD~-I? D$Xvf3.8 K)8vofr9!f@ \NOiB",I'QL̂%\$28YgtydЋ۠F>d__-I[#u@5V;S[l%  =O_Əv~x:^t蕑1ضSH?]QvN7ݑ;gY1u@Y E-r ҉$X'wK3Y@0Z:f0$\cECIlk[V,C>#2,h(HD=x1s/uM\"΍mG"ꑵ`Ej,ޫOwA[-Uzl]PTdC8ow&Fղ4l4DfH;qJ YDR{\z0ƆCS'iEoklYqu\KsUۖގOf4uvs6u?cIkFJ@մ򋵭Ӎo{szfEv"<8ڞB9*eQGl:oO9W8pLW4L;ٟ?b z7uol?_>P#}P,U˸~ h(h@&׽N &MAIOUGSʡPh2+?u{<EFuޛdfj;a.^%?AI{yː'] WTT5Z ON4M'I„=rPDž0HAcM 2/67Ev% JJ̧7wig<&su#DawxuD˸och^͊FCsIpZ <mУ4hm}n6zS!0A+[iSclWf:;Lї0>m6]G䐎 cd ܓv눖tT7#::‡oL.S]6Os8i]Gl|·v排˝/iHt;ʌlol }s'C\ h(3_7m>";L̘biV؞^; j(9"ہ"u8e蝰1) oH=1CUEbiuD@U%A黭z9˕IJ`c#.0+vٌ|uD@Ux^p(`C^xKt0"$b ZZzuD@U> stream x՝{TwE1b6H}5jU۠Ɔ&ӺFch|%c06&*IjcԪDE|">(oϮ;`g3sggwN;Z 2 8u A(#4hJ: Ewx'EFq!ș'qBw+QMiH J>g(ԡ v*J|-d ](r0)B~Vv j%`xwάW2I#6m, )/θ{JɂA&=gH ۰}-Gрi]=\඼ ZWT`]fFg6]C]/oZ X{+&R^{9ސŸ̘ "D[ST@;fJVQ006#+* 19Bq,ˋt[ӛbd+ ti_m=݀4#@^5E*rfX} X oZէ㰄v`H5[5^rU.E)9 A,oṱn6J`ˏ dKP(kAUCYū)$&?.lqP=$ͶaY gÕX`D|GD؎JtxS]T6m l~Կr` f=~BR/I@Jl"- 4b=t07$ qvVo%>>݈U^FʰL:Z*2PF/42:)ۥk68ĥ֤ MVqm3A7KEfW#.L,& Y3n4<iUxv_7,O7dO) *E<%QP-_uU9OW]P rVaB(|QDt:uO5tjD8J3.bB'ǽ `ZJ~CԞQ໥e tVpy'*x7#$> stream x]lu B!IAޗ j7 yq SEyK܏]*H )YRL' `l4^Y$gYQiܝDjvaa=snNLZ}YDX=NͅltJN 6 KlgIEXz1]LTb$Wdy@WbӡUR*",SO`_87Y$NWȤeϱ՘΍* \?}◫V ?B#3R+=$I?4>"d.B(B(*+j@P%e8Iӡc,S+ͫqP鸀Ch]r@@YԾ\\c\I577nDGJƱ|5h]zB^ӏ7(tRXW!-thyC6p~nFF}l4L t6djeIFxE\" 3J? ۆ2`Y{n^'SthOD߲m[!=($I[Vʸ'/Sth'POCBaC^$IFn=a:ȶP` )-KIGؓe:ӐX^Pc:2NAف̌pӢ1`T0&gpg~~-v8=Rt\A^ˍnt:EAM eJ-qՍ%Z[ͦL*y={>:5@&U%Zi^e~"-UpRM2ØTHAMUsB=MUcvZn) *Lu-Bꤒ;(}Қ>IJh<8>at\OŸ%Ӫ=Q: c,gaeӚ򲃠ÅL&U%fT+q*Utd-9NkF(@RXVXrvZnȴCj]9;aݲ޷P畺4]zE+g%h5 JhynYv,0%jc5 -@ؾJi]rA94J-qQlK&;"LPN p{qqхO-AguӪ=ΝV+̍e6ٿ~vZ>فȶN; &]gK6n*ldKD\1ӂ}zES:vgNkt$'tsuNK. *X8Z҇i]Bz0?N|jV푲ùsZvFi vF3e5 (ALEv8h%K4&uYDn`bA;--lZZ]X(|A;-)w_jBljGv7Ģ~?i,pNj5i,sA=T( Z隊)w-8ffUSBy4+yL,J_9]p:;i8 N.;9;-"8i8yA\v = N2dG6QFsy뵋׵Ӻew؁2"r&U޾]yp'?xv!$6l2`lq#ϓƑ4]FDk27Z>yC=q=GIZ,K5lSГK7;W3 c%a,B!9䢳^,c (Ki@YpҶ"ەGz-nݵ^}ϫ@Y.rd_MLAYu(gU0@``7xwdvtR (| o ׊~1^}5aL%=WuimA-7A^ՋǶi*Uq.yL٣!ʙE&XZx?Z|{uhGn|?>_hMQ^9LEnIm=3sssK_M;' e=43^s->˗^6>Ϊ%0{\kы [x> \}kI]DM;h<[xȏkb4y7M$IWƗ#]l}Ã-> stream x՝{\_nT4)E45Lfs"˲'5/:pYL -eeje &"HQrS;e;［ݝoAhL:}n4t(SCfo[Ŕ|:sp) Shzʏgj;7s~.#&iE~ ]Ǡb|&E\G<|!9aWn%}yY$;_0hz!t,b5xXNd3K$tggM}՝e-AۋŗQهA~6:xs7y۔!uovxViTpr:aCءanQei;Vp6SVPbηkȸɳ4""fzR=I en~unl)9G>!Q!,i.8=jl5>Og"lѺ#PKH\W̯}_O"316>333F$~n!0=_ŦNO%z^[j!·860{ ZO,ēx*.WnY$a8FDX(ۏ?1.YͯYc{rr\+$S%x^2;ph Mo7YPpϙ_+D6Joen|e*FhEq[q.H$O{|:#߫&I_~Vr|p79A IvMɔ#Fgԫ/q=GgTEϠblf;q|;760xw4"ۨڇ`0D,-:(2./D<2Lg.f^?)c\PڃѰr&lcY;_"x;tLb=pT]h7Ɏ'#S~KCɄǡQ|%.7%iB9 zMCE߫D"P"90fn Q+qHFUCCe2Q-q̐s%Gki^].o+?p n)A #):M4T8\{WǥK}+Yw6G*pE<Η `O" (YQc| :$JdHER"5IՑ$6fD3Ds *MU!e6JHbg+'gƇ|p-JYsOROj=dۖk,5w 0uъ*t5.t$Mx^ևxpLWsLrƊ|"&&eV֜ηF F O8mo;.J7W2^י<S^{p| I"*e3Wo2vW0|-"P҇ae d5sZOAgnЉxjb %X?GAUHOJ%qb .(μϔ^D7}=0^l;QMpo *f+SY*y-/{j!BT((a{t8D LKl_=L_E@=Ӧ\*H}HtdƸp/A3ݠkF6ڏz{. 9/ˆwx HĈ@.vp]ǹ^aAe=8#aa[FYcD-=VIyT5Cu@zz%Ժ_Ӗ5Ǔ]5cBͯg.JaK0}-pEkO \H |fO8+$ݬ\M[ )ѸۧMՈa@%GHD!HlGBɩ-D?7m a1UJzA-~i?u }j"d#$UxF5I=~bvc{EB`Zl{H u5tQ%Q:Pg5PFԚD$1!zڞ܎ &QJJSv1<<v)Pn+cdҧ!2V^(=갼KuNE\ T`'9"'q?sKJTacQalo槜_~x۶xy"𝝘v>{M-㤃$ '?=gWi,5Y8U`7ge=.ޞd&pթ"?㎦U\:is\0LuYj 꽓4% %j[p)oxW7 #MNNgPkS鎢[=b \BUA3o%`2{P*Z| @d`Ӛ lO4-xksҞf amk-Zm  >?zO10,i ~l?Z4Ӡh ~d^넁[1p?PNnuǓ Jq[Q-x>8xL"%cm=83&C4M3A5]09?Xi]> stream xnF{]$ÀeYF/R 6pE4 J>>j\S  d3‡fXc͏EǪˢ&&uUw_0_p<™+paqṙ'?כ;szz⧕lذ]2Ζ~zۦhe/k|\/tzzr~s3[:3ggdm{̙T"21xfX\*u96lҖuGB,Kkc1.3"e]QEg\;.-}\kd pMmӾ~Lֺjϖ|U͇7WfawѸP$ˠp헕iB?܎^~94M{ZxXiypSjq)GM5U[i \Aד >+Oz4EYs&?+nB  5SBo{=)<6ǃ"9)df.p2wi!By] ='BM̗'֒h(G48jC@ 8K"6J(.W}cAu @BRcL519D1\2 ozXۿ%+ a}#q$ˆb4-he !Ԅ'm Ad£т_rduʃyW|HqfFeܑifYvٯ^z<0s{"9-\YM wX( ^P(K Ơ;QطCd{Q.#grfIhdytlŜ_h‰x>$MEK CtELmG,hI02Q=%%Y" JD) 5zo2=j<6s|hԛ^c,^"{6&.9.gEy.!ջM.HWEΒA0Yv55w91Qp<&FzhиH`˞gDAz5sp_7_^\,QH&YLK% ؔcR_q!ԡ5P2q^SP2z lj1_ٹ ue.# ]&i_5ɘ9hj搕aDj&cIK"-{ jX%qf$sD1QTEk>vNGS 094!R s5m]0]GFsL|*?ӛJ}VޘH+c jsΗ@`>O!<ۏ꠰"_%dΰ>4%$ǛDiXC#BΆiیR_0"͈o =+־>Ar49n_A퍍8cƊb(#ch{UDZtA=sGUqz5vR1Fg!ةeRA<@0XƔ lіH>i,쇗> stream x]ێ6}WyU~ uY v_$@$`?!˲Ģ)r;Hbթ Ta㌳WuAO7nj43%3O}Qfly#Xi|esA__>~קo<1xa=~}ZSJ;nYVPe]%vL8^I&8\2%H+9ތSP/"XvzG?v}x|/7o?}y~y\>ݱ;VO͋fBן7YY1-\߱_75v˹j~tƛm8x9w\TN F>@΅]h&(BcTs;6sc[V:V vW+bRTJmV3#N 7\ArH)ϐ!EB axH$͞Z74{QJW=A GgHyoA;),}AF><@5:Ȝ/׌mEPcw2gv`D\!0PsQ zɃ3{"ਢBJg!e])X0e?kyvs&@FScpтkŸIZoŬݧYcH] +:coӪmx +R\Bhv 8hyDo:%_Wɡk,PHi|>*iz@z *^G L,*'r<> 9ȳ_0:. +b`l͒1˦|aqJ.(렊zՉ%=p| 8@zz,QAXNT5,Ǥփe&Vvs*7\}pA߰2Fs0du!>"'&T_( 3 `rpHE)7dԆӕa2i3hT.: F093YJg7)dm쮺ÛRΫz] x 0AY*膃#:c|yrapn^MڧBBn;@" 2¾88=DmdqT*3 ZNr.Ír 9 /olN VPFO^U̔*ȳ1p"WyNYte1̮i>sa]IFd4`˒E(`]Uy(~K&t? / lcLCx7WT>.G裮WO ohkYCtWHW"<,/B:n"ꄃ,.ջVypDrdyٙ "zr"t&]ONh\-[sJoDcW%#w &9%`v<ܨtcR?];);蘡W'1_6 j7J6ɲ9vϺT爱zøQi#8hlχ 2K.3XE7$ I ~ަ&ur\5gar?Rnw8Wa }Ơ0tXΫt]6 =tlh=rwU`Pz֨TBNU<4^ EWj, 9 G줴Z-Ba!\qBr#=>RM K`!L369&MF Ƥ nਘtGq-9^R`PB@`qa$`=c,h."L2Z飨bCzֹy %  v*-F#ojX `#3 j&gvH|Oz4a/эb@ksp"%~X3iNws'<݌3B왌nq5&2J U! dWa G(Pt3Gs Ed9j\Sfr^@h&~"A`t2Y49x){};1Ic8nfg/}ťt .ERE17@PUO8p="XhJ` O;$rE+ N^m4%;MzvKp]M{G\ M%|G{Bn BGr{Bn ^wm{Gp M%˛y7t7|7#}yn iѴkBk,Ju%7+[YZFw^.tͿ%gOo{ endstream endobj 96 0 obj <> stream xw\Splmku-*9{ъ q #QD*"VEE(*C,da%{d_񴷷a @ޛn {s@oAPlllH$0VVV6>C"[\\E@XEE@HIIv~~~ EEE@rE"@$~~~ϟV;@KTTT\nwdvw+ Nieeݭ z@2UUUikkww+HzvL<OEE[@B<^I %eaǫГ@KDz:1ӦM;x`'\t555AEф)**ﺾm=3Г@KDAvر{ѣG'%%'O\ZZLLLڽgq qց,rѷfWHNN.))v idžeeeТvJHHcw_нD0`@bb"zVVV6!JZ8dȐsK%\.J '00P^^i4ZCCCqqP~nlJk}r={=|r[[ۂvڵks=tP+Ν?fE\8:::tȑ#AAAhɓ'\.oݻwoUVV;wˀ>ɩ*l6o߾jjj޳5b$g^GWWwĈ&MRPPFMLL.]&''wk׮9r_[bhhɓh?ǏGGyyyXe#F8qY5k<~ׯ`0m6u%KL8hyKd8p`ƍSWWǞN>}ܹUYRFFfܹϟ?G t͛MdɒI&矟=.ٵk_\\:4338o=ztȐ!vvvi Z #;Æ eM.~ŋ߻woƌ_@ h}7rȐl̙3tȏ?oo֏lakHψYf4]~KRT@ŋaÆ֢-rrr$ISSs(7*++:uJ^^ٳh}"%%v-[lÆ gΜ;w.t;w4޽_~9r䈂իhYYY'Oa3ۣ2e ~:G%K]->}:M.^xͧO={>+999//)S(++޽cǎ)))III5vvvɓ/]۷oҤIG_kjj,XuӧOϚ5 ;:zh##3gάZ @KDXf˗.6l_kӦM7nheeenƍC9??x`X7)6Hba㥥.n**%%%4~C__>͞4iM5jv*OGGg([VTT`2 @)WX>}z5h u7l䄭3LYYYBK99y5RJJg3gtߧ`7c^n[br!(Ua"%ܾ}{ҤID]XѣG1gii閦l1?oٲ-rҥK ch͛mllp|~Ɣ 0 n)?Xy\y)ʦM\i{fIKKޟWVVI/ήf999#GDyaaaj˖-o:Tgl}EEEixfff۶m[fkӧOWVVƆ)((f3͛7Mw.4y~zzsnݺzO4?` aee7nhAa;4iΟHNN׷iS۔7mڄ{SWWǞwԩ͝;ĉ^&j )H/fXD 0gڵ ,pppxŋݻ'jgg}M6֭[򊘟---'OaoooaA( `ذa<۲e˶mr v؁O$}||222޽;|p%4~L&Fz왇NJ+h"ooo1 eĈ.\xׯ J:::ھ鶶#Fvrrr455=_"3o!//a𥳐يUVa!Zϋ-n)?ڵܼj3fxU}}=ŒºRi4ZxΝk)FG9/c8<󜐐pQ55? ďC.,,VUU?~\MMH$ Bvʱl6󪪪/^d0u㵴nݺb-,,L&>~@PUU544FsrrL +S3555}}|>11qٲeTWWWQQ=z4CO?cddd_ʪ"uBSNo.;v`㖓Y Xw1g!֏1tP]R~޺u>t$?S۷3QUUզl%?s8~TZ(?_reiB\CCcM777bVh5LګXzB Az#F/_O ߼ys'=*((’MY \tIJJ 墢)Sl߾`ر̙s)S(((`Cܤ:eSS円&LXzȑ#Ϟ>` `B3UQQ;r䈜ʟߗ166>tݻ'|~G!jhh1 +VXxٳgDŋXhjj:hР{cƌAǽ|ΝqtssG&Q(>H&ׅG&_|)T%77 BbOyO:ۅ yyy͞ %^^^_NDDDKEwR{5=dIIId2!!!d2-//wqq!؅!j*/!2Adp;| ?ǏzīURRݑYẋ$?YO%}.tfQ×0P***/VQQiGeee:::gdjNaP 3Áгw|b5( ~ !ǎ]O3grtP2# \]]-$5VbY/_Fu*++kol.?#]jc)iDFF K`0tuu!3tuu.jJ__(!H$RTTD$žۿKI5TJ4|tuu) tJ6MPuuuD٤D"S-! H2/v-vO#2KI{PJ8 ՕD")Ƀg{ꌌ:]#|>ÇD"׷s.<L&kkk>+h5fG<񹬊z+G}}'!GPlllH$rwYHWO)HZtJI]ԩS@yIlJIWC)ihӧOwp.c@ף2"TJ:_ 㢻 :rϞ={=|l~f)'S))PJ$'((ȑ#))) 033sDhhl.??9PJ$ԅ(#dߺu j\pyJJIB)i0/IMM(**jX, Dhz _PRXJ5XJ=)Jw;6}k׮qpd#=⾷ֶ*,,wD{|d#KIeUB)iZ***0Y0LUU\ሩ]jjjdraa!^~~~ HeCE4S)鏵\]@II!r]ve$!drwʪ[!u4^R>u54$i4% dz`Xb!"ؑ@쪪/% n% ǻu떹9>A(++ÈtTTTtp ##"򳣣cRRRwbbbN~];w1 14Ni IRJI@Lj䤎C$EٳX\p8}ZGvŋu-Z z[}ܻwIyy9QMM͛7Ϝ9~9077?w(JGbb" ,--Ϟ=_p~еZӧO1ZZZZ KNN>wܥK:7n9s@D2/޽J <}Ν;}^EuuL7ԩN?h+$WYaͶ(**9^1OKIcU6@H~޲eˆ n޼qF>Fn?~\JJ I$Çw޽elW&LuٳO:Dϛ7ŋaaa#Fp;wz3g`?}9sO|oܹ- 155={5kPKKKA>}LEt1vpttϟ9sftt4z8aEEŖ9r-ZAeeeWZEӱSRRߛ2aϞ=XmKyXNWWWt&%%%}i7%%%urrr222ȨM2EMM{>|ݻwEû8?[ZZaE舲ՠAtBbر&&&rrrX?ϝKg{]#KI@)ihԩSgyyٳg+cNNNG&Lx]KO|>oIOO~:|l?Bó+X۷k¹sYYYg9s`6l;SgdkkyE\]]I$RMMM'4%b~@CCC`gdd4J(?WWWAD|lF NMME't:=,,,33!R\SSGl! ίR &b~Ç}|~f2M&[}?0?.rap|IEP|?@ PPP2 """Zzj~!66{8u/^X6r 7׷yɏ?Ʒeee}A]md2o߾mddy3nxxx -yښyѣm6k֬u$5>>>gR(9994cxpp̙3 jԌ=z3gܰavnBZZg^t7cbbƌ=N9!"gkk7bڏ熆e˖u|@ϟEg3J8ޥ2s>r0O8w _l͚5X4vQa[󳲲27dl(o笁Iwܙ4ilbbaC3߿JJJK/%qy-@hs^|[YYIxmشi߿QQQ9r~7fϞӒH$/h… J3f  GݻW&&&(ݻ-1c6+?TWWKIIUTT`nҥ666}~Yn4xFd&+)])xlpX~v-4~EHt YY١COVVj%?xڵaÆڵkѢE/_Daƍ?V^vZԡ\UUrӧ^zo߾~l~رc͛''' Zn=??^ϟ?G7~={ZjӦMf3 >|׮] .otΝNرcB_@g1?9RVVvʔ)GE̙Çjmۆj\`׮*((|r n|/483?? ERժBCC_6m$RVV;YBDžd޺uK2˃i *=LHH+4g„ YYY=0a֭[<޿_QQ['..nРA>>??ydժU~߸~뱇 B_WM6lذW˿yڪ 鼲Znv'zp=~G}X?9(Lq]Rͭ򘽦Wk,%t oO*`ѻy4puu50 )/M?Rp0O25{\״U@@vIIIg )))9˗/cL387n۲e `޽{===㱅?# N]oS~NKKׯ.rByĈqqqM_ɑF9rtڴiW^EƌwlGY^Q7qxKw= Gfl+[Xq#YO"i/c y(%]VVsL՗q9 p[Ln#7Cc#djܽ{3rNhSF%۬H&4m„ 5o߮bgg6cUWWw̙'O5jTRRZަ&Om67n߾](?+))^L& ]޳gϚ5k/]4~s۷ONNkʕ+a`Iye܏BvL6+|qBu $1;3K9EUuE=/f뺨49{ѭ3!z>|zdj0?ظ3CCCTZ'ql``Uӑ64ƍ_zF|x333Cutt(ojjz5X#2ՙA`,---,,ESSSTpuSSS0337oGFcx>_@e?r9"v\+4= :5Od3X%Jne=& ~?ҘSJZO_ep\@.xt"++D"}v|}}{PTT&6#.jIII˗/=z~9J={KLLL,XpɮiĒ:_KT7^Ϙώd%3;xG|),VRAe5::Or5*%JI犵 yroqyu8@r@444X8~rhhh`貨bpܐ2 W:*_Q˯Q!Ƌhgi/> Kg]]uP) *thR@u֓A>|H$}}};x%h7W\\K$>|ئ) T頃I$r݊輲ƎvT+8OwB|⫥X? ++RKI%0ҊٴFz_ 3P( {)eeedcclu׿xr$&&5 4E$;o6vEEED"[h,~e=Qw!>D˘B|OCߧd(E [xKIӓ m,% KA~t=accsqOII!PS,PոnLVH4nc!dr>rR>fq|Gu yf*Ws;6Lc)nT&-RT4ݞyߺ[뛮pʡ195n"_,- .~~~!<<\P([MM6L.,,R݈dmmm$,~?34g2Q{P s._^ǍayD=h9)%-_}?ܻmbZM;/^|![wBԅnOǾ#C7?Ϝl0F ^[{*%%Wt ?.͗\{g.//OWWbˑN jv#=b#vvv;B|"vl+x={Ta dx Py yWJIGf6n:zDY~TݓCSK3~:$/r7\P3[~Cچݞݙ`g٭sZϭ ?z :~'Oq,GVVFLLv赘l~ B|^cA&: r<q0IJ!CW~ͫ]W]cZ195W_yǭԒCچ/۴C @O={|Ś nӗ]Ywڴcς%+3F]^㈭AQԍ/hN*srg K9|xn3Od6Ci&~el *Xz=g êֶo޼!aNNfTTvMQ:.*zihP{ڋ_"?}OOj,ܡ.m*ƌ;w62㲥!*_|v;>y!;a hɊ55DghꟚ8g3+Ԓw]yz?pDkN<'N>auL܎/hxx9,NG-[efeR?FfVk6n?~SPv?J~N*45=jtvOptػߏB~Lh/յp8ba^^xW~E}pldWyI(;CPtͫ;wVv䟆78c[+¦Jc^Ƕ| !GT]#(obW,f s84ltC9tR+=gK63f &55UCCCUtɓ'?~(hiiu{GNrALɍW&:9o;ZuB+84z3qgfy8l|삥_}2m؈Qg;͘gh &n~+l{Ԧ)20/h)3^tpxtZl_LFTݼ}l}W?cQ{k@~ B~~~ϟ>}}} ^` k8%s&}*tN2JEUS|K87BeuR:3+[f_Z_|~CMd/+.\nNcuxʐŢ;G~hi$ɔ3|~}'vib䟆xnߣρ":FH8b2bmNNαcdXrhkkiNwhrVv R ٮiy!t|:dѲUξ )eoAݭq*.X",&#nj=i~ Q' o7j̸PXYy9w^W([._q8 BLtO^y%+`K;#Pf,>?GTNK{@iiy͠!?A~NS'wfeeuԩﭬLGG͛7hZ`0\]]I$Rw_ڻr]БdbZYK%[7MGˌ~ ʴh,vh6!/_dZ6~? >ZfP:mC'8_Ww? /?qN7:wnAC~5fܴMGr~]g<.~}ڷ#F Fv:ggg<|㣃*++uuu_|)" CWW˫{=޾[!:3YD| ##qƬ"3Q4H:~/%?[?pV3g̪<}Ƥi3W#x ϵ}bʵ4u #x;N]pi4իWMLL:VUU!݊^-77Ȩ[ͺ3Yty17 &_J~˯7>?7ui3f `vʧ.Zc@ɼAbٷNJCWVVWvzꕔv ׂ -Z_!44tݺun:q ƫٴiӸq~1cƘ4v}PRRRm[`` *++?3gjܽ{JJJbo]o$++KGGѣGQWWgdd$p***0{{vw+I;ETR{ҋ%2ަ0#iyRQQi(I-6VYY h%?=ȑ#hnc gɱ}?:熆{.gFh4ڕ+WN>]QQёן8qQ|MɠE|GLQY-e =B88|xzx+RUmt@E7Dϛ6m;v,˽z]P~R8t:fΝзo߹s N Zpѓ'O~A7@5D"ݾ}[ \vhԨQSLyc74g(?{n̙}?~qq1edd zGĺLTEBBBO޷o w!##3rHMMM.]?w…X=B_ϟ?~xqqqޓ&M4hB됐3fwѢEmt///ۑ444:uA|걾HQ"'2<tU,=.[ډ),ۣ qa{ήi%?oذaǎK,RRRcW_ٳf_^WW> X6551cF_8P__w燄L8J]]ҥK;{F[dɡCgϞ͙3iTj>}+++Y,֚5k'$$L;}7¦۷rUUZzя\.WAAի|>f$555|󍪪jUU\rɓ'&ƺIqqfiW_}o߾j&b )))=};(33S[[AN>moo]@[Gv&z8à2vDF7Vjji=pzSٷ:?mkkkt *gEEE777K|6?KIIaÆoݺyfM󳆆@ صk׳gСCZϚ`Νh(O?|޽K6m?z:aّ .o4?ǁ\vm׮]~9 @VV63gv+W+x1'g)))&ﮒ˗/ٳ%%{OOvn*c9 ٳgݻbInƏ=jׯ_W{~>}*!C,?dxR#h%l^ /s د- u}eeDH Kd2|M3V7nįIgԨQMӔwٶm9s=}TUUѣ ˼}6Ûώ#GTAen+'õwalln:ZXr(q/--i_z=0 33;w@nʕ+C2dȸqnܸ!өS>|mHJJ :|e( ŋ׬Yl!$ _7oޅ o!?-l']ě{yg4k-嵸Z5<[qYwh@ CCCCÇc[m۶LRmeK9??r縸Çc9Yh-g333۷o mx)%?#999zzzaaa]EXGGvGw&inn~-"%3O>L 3HT?<NK.`sZR^uTr?6AsDH熆~ʕ+QQQǎSPPh=? Ǐ4͛AAAֳgr-粲2ii/_fgg[YY7#yժUW^ц rss}||Z'NtppHKK###[7?#)))O>q5._|YQ6bYXX@nJfkkx˟ `bb+luuut*UWWrwשּׁ3Luuu𚇇p?GER?AcGFFGOgEEE 4 z:,]~ڸq """yh4uuuӜ`_f`` s8aÆ+W8q}Rb/?D5446oެɌ3&O\]]۫W^vݼyCq"Hϟ}o_|߾=˗/_vH>QsIIɘ1c֭[_ɞ={Ǐ:u*DxwᤤQF%&&/Z@QF999޼ys„ wj̉'>d|~{9sL,#Gܸqchh(~['Ĝ;wnȐ!_g|rވ#lmmO>=f&"##Gꚛkmm=ydQ())Agrb1,0Z\ ?vK *; 6#]Lgh]_M6ᗌ5ZqxAAAGjGo[kkk?y}\;_D뮪266('ږC_7o|-lڵkщ$ѝz ɝ6&lC8AGZ5 | y]z4ǀ,!edd|@'LLL,Y{'Ob/SQQ 8qٳvΘ1]*$l.?1NdҘL+fG8Sam;.9222,--;6az'tggÇ?zSpD|/4557XXXtqE>Վŋ B1?-[l۶mk֬6a,,,KV^mool gT ϕ ky-gCCqY5򳬬,g^|PK NJ+H.`ҙ mTS?l"vY***0jahC9rͭiECc9>}ڎw&ǻu떹y[H$7 Ǐ JKKï b~~ɞ={Z:d=5kۍ.֤P('N}6V;P@:44tX7z޽{O8D^xqnn.'//,//Pp8X;{(x<<Javp\U,UK+fChAIIIwt) ֭o޼Ì---ϝ;׎|>Ν;fff]%>|xذaRRRsy /^_Alii8xD@#F 驩َzz|>޽{gϞ+Meeejժ.{;~xgsG2{-0Q| Kd+yvP(Gb@奫`fjjjddԑ EޟϞ=kkyg>oooiTwusΡZ eʕ%g1>| #E4?Q^מA\ (@S60#hEU0^ >$HЉl6B-++>⌌LMMF̊W]]ŹsհEpԩ.Q2uer+//]lټyvލ}A_ *;4Ă⿊rh3yH"v{{N h,kjjڴ+DjV_:WWW6 q/y-Ce=Ivh@2544QP^uNWSK=WAxt$''ЍP33ϟ?O"Ļg>x捎D3]i)lmI55VAc"i;M*f'yRSS544yN8qiw4Uazɏ`l8G#T6<'Xaso S@100?럗燅YXXqh,ymmb16 Gg\irY,yAۗ QYPНTTT\a2\._KKƦT\D"QP--.^尜h٬ΨVv3$<x)y#b<== ½{11wK?.XpMMͼ|ӧL刊xz'Tv g0­^҅yG{:, vudݻG <==Y,1 \x...刉S;qyBk}YUAd&'.4*ZTHJY*--uww322ZYv4XCliiXFݣnnn刏'^z_^~A{ B)LD}ĉ9;;DQqJJJ//|xF>j%2B)L;EdɒѣG܄spp ok.#F3kZmkm[*Zj[k.ֶvT!Ȫ"A6 B1 Bɾ!Nٓɯ8 xޯc̙3' |s>xΞ={=N߿~uݻwG3 !JUqwdd$11EDDJt: H!A ã~RAAAJ*dd^Q?+Wdxx.Ohhh__RY$ݺu ǓHމˤh~),,%3z)//GqqqiWWWPXII2~AtDH.` j:yϞ=J;v7.j*Pߒd}ݺu`0K,pCC-[l߾ Ezz͟~iٲeHZZZVX:::be˖û=sN==7|L_z-<O?^_|YFQ!矷oߎիW#ĉ#H_~+bhhܹsxoСC$̙3 B?Ot:g9l:(l&Ҥ>,{VF 6V\ Jgdoh۷X+Wvvv"9--m͚5\.fhh`7or<$$_~ {BxLqBب vvv\.P(֭xp\.ONN^v-27 \./.LLL\n'900j*BEEի9gddz y9zzziiijsw133|TdQQQr444i 4]l)Tiz#B(hSQ!Sl*pzK.;99a0X#bcc~mx~000 HK.e{{ahhlNI??䓊煻wiϝ;w-Wp8طo/ǟ?l"^d0/\_2 o]!!!/W_}1x=='O9hHŧrOԄFg:wPZ.H,!vSxnx/ 3D}<00z'OFEEEr|xxgqqq?`˖-X+Z333<gr<o!呑ɓ'=#ypppӦMp%~vppa6l_mۖ {tbqFFӊ+nݺ5edׯ[[[cذ D{' *ի'A%---h4://o0}òt +cUj yٶ~gΜсsqqs=d̙3pݷorO?4~vuu=r;J?3 /_gϞ k֬E2ٶmt믿9<h acccff6W+!!]x1++k&ü źtRSR͛X,vb綶6ss󜜜tX`GdJ^}d.S54 _EW0;*ǔ3y瑸 .]7C~rxMM͒%K\^ ;0V??S{۱c.bK/=ztǎ-8 駟ttt w'nٲ嫯:r䈮H mvĻooߜ:u ~v^~eCCݻwLj~޿ iST<**^_ |TxFΝ; Gnܸqn_١L##g޹sW6ڼp8\VV̢h42^N 9 A,JϫԼ.S9?Q(v `&BUEە޹D"T҂*Mu0U%KH$ܱ̰2PZZl62*$ye2Y^^NGwtt4+QRR~ssnvv6žx ȠJ&t:޽{ӎ[@PC,`0'NDEE0_vFHU?:R!e29Yh A)Yk!HB6L /0Ӹ ю(EEE6Nii=Rƍrp8uByu[y䣏>`EuɕRnnnFFF^^^wU/ p^^^mmmS=,11qveiiIP4Y`ዠzѭ<^yH4sN_x.m d` X ,8nnnF2%޽{αPG"PT4}%đ׵pqq]@Ubb: B1T(6yb#uI+`JK`bC**MÜyL&ի8.""r~@kjj>iAERױXx&666qqq,0w$1@4It'liL>+~`0&Mh! x{{{\\ܙ3gsrrsˍ411FXԡΝ;*r8[[[$< KV<^~P@ryA0lܱe6womFhh(D^4 ˵kUq8N?ѹs(T)4E__˗a=,Hg6QϟGү+244doogLlxB-˅ yNV!o-P Zb$]&o,dd2Ygg'J`0sA'h}ttO :,J]6^,𰓓gf|^vp-å29R@g'@wJ>pBCC1`!okkK$vEJigz`kk[XX!%%%(*))i..{ԩWjLA3b xLG]KBS-!^*E 799@ ]p!##cJfHyybV c9.\069;;k[ZC {$q A?W3<{1_P?Qun0Q&h%</;;H$)f= ͵hjjT*p JKHHЀy5F+7EQM ,W)e|v~D`0ñXUdddUUlGKҴ4sss"=ib 56@ 8{lPPЀ_zr: /3& in6̷5 ӧO ;H$GP!!!l6{,JB- ̴1lir)?9yԯ/]Hwd|^XYYVWWoT LD"馦jΘ6Baaaa`` rrr"JUS쐐 ?7Haa! JIIQ,^^^H UXCҴ ABW3[Il"v!yB !TdB-P APMM͍7lll0Lhhhyy6DyZZJb:uG1C"\xD@ pewۅw<^{",ʓK' ɾ "lqeNLLtuu522rl:77wD"YZZ*xH? EhΈ,)uIdڭ|6 4H%N8 mxHha{I\nVVkbb:fjd2ǫrPTD&D9NX e9˜|^uxA7Jby֋-EZB݋YA,3mllnܸQSSOB[[[0^ޓ'O|D& `x 0M(VHU% $S|7ğD>>*`$IxxAPPPٳgg( z<^ExLF8?2QQZ$ x<т\@ky$ @KxnTwww###OO􁁁i&ܹcffvefz(*55ބ ($$HhPq(:W,i2M;%|dxԔ#Ǚ,ᡒ4Annn@@ӧccc[ZZϏ611;iɓ/^c9  wvvVJ(!CMʹQAryA0?AOl͒͛Ս+JCCCkjq5d<|2*22 ņ3i * /+WXYY!իNҬC` @-[yzтj yNV!Lg"fn֎@c#io߾ ZXXL\ɓpvvv߼x:voEE#<=a 5+ŋ&7m9NN[n*`mm=Dڿ\ gE:;;\\\DbvvTGY,֥Kh4JUyyy(Fׯ_wrr',l$Rye˫r?z+129~3pDIn:xT}}ʕ+'o?F>&&f&=ܿJ׮tn۶Mʇ277鉉ێ;X/X?;99}[g-ahh(##… FFF!99Wڼp8\VVH$?~'>Eh4o6I^>L ڦxOMT&y95*Ur*aN FM?\xq~<ro2)>>~ŊV lllD|klvLL vFDߴ+x$ #奥h62(I$ҙ3gz:@ZCHGGR}X?#2lٲeȧ.//'nnn555Jߞ~+dzX,xgϞ=<]1%!!add$## >Ø8ʽ{x|pppXX~.++Sx>z7mmmn݊>V?n:㭭/D:y޽{K.}ᇾ.]ڰaCpp09zj=++kݺu!!!w>{,܎~O?4~z___oou*VI?^xZf ,}TMbcc}}}.]z鬬,\aÆ/^paݺu;v8t萁֭[h4\>~ \fM+ܾ}gҥ999/OOwyp}"sׯ礷 jR__mooF|RZZjoorssQ(Tzz\.c>ғ3,XqAQ붻6w*ѿ"N I׎]ɧ4PS?3L==#Y,Z ,˳qfE,wyڵsHH^]]O(jN{) RZ+&ʹ:Q9aC$~?Ͽ[Xw\?55u͚5c7\]]gwww;;;xСCH0_/[.P(/v兜w𺓓# ###< ˡ8O?poyudX+V?3P(+++p…脄̲j5222+,B;wt:}dp8޿_ $&&ZYY) KMwdn!H.o*}C X9Ndc@[`A~f0555/bee%kkkx Ő˧~r~޲e ,G'd2Y dS}vZxV Tw}۷o߲e k~fُ(yaT_~%Rаr>&p!\d Qy䑞g}yQϵyB6裏VVV*~ׯ_80;WL&3//NW9;;p8CC~ 988P2LRLfSSBA,RieeeDDz*T1Allixx88Z֯_?o߾ѓ~~~o?ѣpƍoݺ䯿ZQ?#wQ<>W1%lccw^ vڢ"xҟ~]l;~kccl"/Ug^{5$wV?{xx(k=zT1X<::zl7o 7=<<)gPxHcǎ!v??yF!z>;;^{J4 Ajiia24L&_r% @ 899p8#GpSN@D&ݻd2T[:;;߻wolA.ibb󻺺SRRXJ4ߊ,Jn4hh|^zG$jS~FsMM͖-[>{po /XytR]]?((HQ?ܹ>Z~b,-[w}Q@OOo͚5}ݶm8?wڵk>CWWWE / {\nݺp݈Vr9xW OD1`RSSڵKqÇׯ_p֭+V }yyMtuu[o!!g}VG,n?g;͛+WD{Y8>Ν;a--,--7o믿9rdƍ$i;j5kjXbLfff&B!D"@ aX==cǎp8k׮̂&fjp޽eddFR ._lffvΝ'Nܾ}(+Y u~;rAB1xtGn9. Aq#z:ۑG APyy;;;UQjllDby}쌉,,,T3K6եaLЦ\@APGG!Jt:)aX9d2nNn:$?s r}:k׮ .(db1r]lvptАH$}!OSSS!t:]ɔX Ni6o|U[[[^^H&}||5311p+000***...33dXMS" ._B:::|||,,,tzvv6 177WrY ;òt +QÓ~?:Rw ^0J-_;! i.zlvRRҺup>Ȱ!ywUsk.#&l6{5fцm X,&YRRE p8&>>>d2911133b},FEE8qO6%%ٳfff3~N"_$]Ɠ.㋳"UVv4V宁ֻzj~蕂^}d7JbyuR# H¢m. ݲe k׮WMٳgׯ_i67쮮.&YPPI&];bH & %33d644X,EisΝgdff ;99>}"8Sn=mt@u1)OtyMI \YK1>T;Lؽ }cK_A,Z?jIȔhp`voH=BP<>>>))رcFFFp\ ]* ׁ7XV\SGDufj~ dj|]([m"ځݜQg6q#J  TbLfVVJ%ɡo8-00իd2N1̎~DRQQbݏ?~رÇWVVΣ~vq258֪;i{c,,YXaw2 w&p\2⮚iMFr!_'c9Z$Stٔb@#"`kk;߽XBU__`0233drPP/@􌍍q8g``7\miiy~M>xuN9XioLqf"om쁷&k6[W=Nx'ӷme؟/;z[o9BZ@D %) `0T*S10Cd2Ygg'J`0 @ihhΎutt444DΎǎׇQ?KZB'{vz^oR]WyD?l{RW|^q.a|ɞvܰV)Hf׼eJR~872LHuu5HEokkK$:/,,LHH|3gLMMO:Ur333[[[x"F,. ֮Y ާR7.{A  ngf|!uzYؗc5Vk~ERau}Z]leO@HƢ%RV!ȩN^x!OGOOOYYB b~zzzzmm-ygllfjjjaaahhHΣ~>{, W'/{v)1zo=e6^o}Ň  u-_ %(f)xo6'SxռgTX*2)$0BD(_P?'vqR)_H3CCCׯ_;|0P(eeeHfO%0ӧSSS ɓ'1hsM^&ݏ}eܬw%[6oY^zS~<3KrWW|>ٳO+纲ؕ+w;=~.Ί|a{k[j~KEیBxAN`ዠ;%ҦnaIn7 󱱱~~~N266655=s˗ &...h4###QQQfff'N HHyߨ,G2ܕW'7W&(.Μvzg-EԬd]Y $YӔܜ԰̣~KEu}]ް֨.bOM={H0+籧Q)N,$@= \) $B݋IДe,d2[YYpILL mkkc0fff---A)ħ*,}lJ b{Y>2H®[Pܞ5(akSS|7ğxnF\ UlX,L&p8GG B|}}߿bgg rL{c Wsi7KTUUq.\(,,4C1 YXlvv` Y`SFÝ6zaJtBE(_5?QR0m4sFFFrrSj葫p}}LWW̴We7Kp8$u;\˗1L~~byYY w|38qBf :35Ԧ}ZGGgӦM"h HكwqrrsNo>޾}w}wW_544ܲe A߿>srrovލ\AOOoX"(;;$<$F4Z o~w3)((ضm\.߰a*v6V? Z ߾}{QQw %Ogdd};Si5kP(wwwx}ҥvոs޺uKGGgpp+~\yyy}KH? ?H/J'_reddb7lkr>߸qc!vlr˸Y688^^^KrsssrrR9F#;:;;o3ܑӜӜ3<BE|F4_qFdbR駟*Uh4XB:::"*O8qYX;p!utt6nW_7w-FMVVVnnnpvܩkJyӦMȦ)宮o6/SlG5/^_KD|?`lΝ;l#i/Xn]UUR^SS;|R,srrMLLOii)S!RpJ!F`q;5f7Q۠Qg9{Dk읦K~Uf&9T*uڵtH}vXN }z֭kY${C2h4͛H$@XvmEEjX3accsĉuKxSS۷o7:u*00PDPjG3+^9EO:!RaAMqŤ$ _1SCAAAqq!D"WqAׯ///GJ)*=e2JsXuE___ŗ[N8^__\_ '..Eb*)~ȸ.喖,x¦(dμK3yw3:h'%` XḎ /f}jڟ9nnnOF6kkk/_2dAhs}}}XXGnnFXEXQ(엂FU>WcUFh>A{5Jn"0 ssBCCuttvڥFMSmذS`TWW+x<7LKKNilvBB‰'lll45GT u͉1RS'A'0sj:ŷ xC¶ zCba;8:v=V`1g: o_q:6# tzqqEb8//$$$N744:u@ L'JD;˵KLL``#&2 z=,k\|E*" 8N=''G9y<^XXΞ&%JBNy6M;%|5.YwZu`<hhh^ILL`"YYYh4:<<I>]]]7nP%H<<]+J)eV` -(&Bbq~~ǃkkkg,OVhL1i AD"gT itJmzMo6`XAL&R &""bJVsIcccxx[vvT󒫉P(q h|w533S1,,M$X29R@HgADctKk@Xp8P L}}}[[["茭=p8;w[YYTB,0444ie]fcc })@0;=D *9>Vwb?*X(H$ͶSDnnnJa(ʉ'T4H 'P~ilOɲ+ߙVϔk&djjzܹ͖gD"555MHHPЦ1$$Del,;\.狠;%Ҧ2 y<6WuLjh+?v}_%PhCCCIII8.&&fn'Q߁$%%[ZZF1" Zu'yr䉸]iubL=&R… Ɓ*'l6H$ZZZT^^ *--UB544h ΙgJ(us݅iukY@E0DDDP(9qR4994::zJX,Uޖ333*`&y~LZ.F_<.ְE9@j"hkk?F/X,ǧ}Prr##,kNPWWݭQbҥKGe SPP*` I~ 3gW ~b^eO1.>P0g@`Tjgg'Gh4 b2t TZ\\ iމƃa0)844B$sp8).,VYʚEH̞*L(n0h4;;;.;*333'ommDPsAN733zT q8ܭ[˥4Y@5m#Ϭ! nIB_(X$_[J-Jjc3 F 40Bqrrbѽiv<௕[^^Brrrƫ \\\"##gM9oE++G4𒮓-q'{hu̞P0;i 3BÇg҂T*-))K!TVVWBp@pU333:>>PTss*HROO@|[[[}/nX)j:ŷ xC| (^Ȩs,ˉʞb7{'==@Ӿ.mmmfffxP#y ,`TTT O'W___gΜP7@ooobbbrr2СCp4ej1vy;]ӧOc0)U}||g/;;BUTTL\-77B9_É.z@I~bJ_Vw3+C(<$|||V^+Whuk>}BCToo~:pbgkkxgގudeee/^466+//8 T`jjT,@mii9uyy9,@??)DT 5#k R*>3+BBM/###/rJJ  ѧE"vd2x<O1n!%%eʕixy\xA*G|Hd25;::nܸann~̙tO<==g,-|}}xk*Ywu].kAA }׆D*VbRظ """( *"Ht tBBo!:7B?ɜ9C朜ߙ!h2,щи3ټmdIxm|Z%JCИz.%ES㚠@ ~{uss6 FZZz̙֭J-l5k|uuuCBBpK,Yl©SuhÆ $ iѣg?aggw}ڵM___ZZZVVvƍiΝ-Zv A9dz]tݖ'NHIIɝ}4ؽ⏑R$%~ \VjP8FF'977WJJ*%%={v }֬YY;?[[[cX𺪪JFFr^nXuQoooPt׮]'O((( F^^>!!ıcǂY3fDEEu_tFFF+hÇsNh;wujjjk''M6544(3fX,vǎ`&NNNiiiC'N/^cbcMfhhߗuOBqqBpp0x`_[[_v!ݻ"VFN>ݱ%MAƽԖY*1s6&S+z %ǡE>42\ @ Q^^?ӧOԫs}~Νo\ryzԩY=/0@ʿ{?~~/''&Olmm 8)tk׮˚5k?|?._|ʕG F#_]7466hGzdO?rJpSÇwSF3+/_z{8;;}۸~l?$-d%u  ED{P(BY;$oܸyi͛7y< AaIIɬY^~={T0 F[ŋĉAe˖uso)**BJV^+𺨨ZEEeڴiPFFfϞ=01cƔ:#X?>}|ﭽ}"@7]p׷;Q… UUUAgsccٳg7mڴw^D#uqq_k6mooe˖#O6lppl6֭[7oN:aÆ?Iߺu />~ lܸyTPP㕕lU.\:GX,;;;ee[>xi+L7nhhh3glذ` ċbnڴIUU/,,Xnݮ]ܹ#FuuoBk&y/tfp%dbA`Rit}[`w@b?#,_ٳguKKO?:B̛7/** Zd_^777O4 ľv8%AK.!jpB///𺱱q„ B!@W|w rb׮]NNN3f 󊩩#R?`0'O}#qss;|mmS[, AWDrrraaaK,r~p8k׮500 D"QNND粲1cƀŪ#HnuN8addbD"Xz#Glݺ@$wv KNN_@;G=vX~~~NNΖ-[@y``իH$jii>> GFF˗aaa۷o5Ν;K&ݻ'##DcRRԩS>zܹs޼yvmll.]􅖖Wۋ8r흝&\KD?!7n\H?G$iHyVV֢Ek999@[FFə2e 8,Y1c߷ohpԩHKׁ}W #==]MM) )==]ZZIb ZEEEII x]nٲ̝;ߘ:u*IJJ ,̘1 JJJZz5xvZSSӾtyf$]rXo?$ue(q &k[%@ QtZ||ׯرc<蘻i8 o+fΜ)WqFȑ#҈F\\>v옛r}-HD6~:2vΝ#G&{GG!& aDZc=z`0>}fnn.h":bw=ztQ<_ZZjooW#CA?]4&[UUejj_suug"3]]]w؁TO?Q?o- `رVZ8qǷ+((_>@?twwߵkvZP'00pÆ ؝;wرLUUF#uϯ_jN7<jjj.]b2o޼QTT砗/M@ ,;k֬ŋ[XXΩG cާDZU.$Jn(х %5@ a4}}}!k &svv>rj19)) ù}';;@Ƨ{<==---I@tl٢ Ro… ONN>}zߕ~x6lp~^^rBuKKK'L*)) f___%%%sss۷oS ?)//ܘ3f y޼yIx<իDT*MbO<)v2dl_fƗEuCY"ƒE !N@ @4"qڍ冄X[[[YYyzzJpgP3T믿LMME_q̙N<+?\y{1pϞ=?ܹ  6 >dחSTTܲeKLL (rʴifΜ9uT555`z#T:r8$K?ߺuk\\('ݼySZZZII zzz^x>}zʔ)s@aMM̙3UUU_n!g~pp%K&LqUd= deeMvQ'Owm@rvv^v¯hjj"}ApĒĒHw/ac,Ҙ8Jb@ &2D`XӬ,SS۷oKD^Hbb"R^sa0s##q&3g|ƝdGE.?4FXFUSYL8Jhus`@SSS$/6d@"LMMlw322;ϟwss}*;33XAٳfJNNI.\8Ǥ̞=Ģ466޿ɒ%ո׷ cHYRPc)c)MPEC `ptt4+ɮ+,,bJWPPF3 0|~HH ڶm(ÚP۷ |N7Rb73<l(<S)J!d`0#lll @2|…k׮Y$!!FYM***0d'{yA=Jw(3d@>BkT6@8T*ёD"XbH$GGGccmnn~EI???׫ :5to% CQbDr|ZPv 2]ec Td`0|||x:d>>>:񢢢 <<<\vqq|r755H3b:ؽ ("Ju4mb\6z$"0h /JKK----,,c^ccc ƥK%1 H[@;B ۹o[Kk`O/iN(. .oH$)@ Dq*//?s挷wgX׮]{#6x<>??;G+`%G *(Jm+-U𶬡' @ BBB}!q222hto\P"ΝpH?"vh+humOQĂ!2Ryyy0 #FnnnlGgY1+hHԷ$F K=~9컴aeeovX,~ppp?yq\wwghn vr2H/fOmWh FmrهHr`q]~Ut}}!;1$jF-3}}}(!O817ށ  /qㆭ&AAAgϞ`(?2XFDCDQ,&@ĿAWɋG%:yxx`Њ .L5ܠFgggBmm;w%ݻAΝ;S1h##V2¨bߕA442?F)T44&68Zt8%c OèB CF999ڊkӧO瓜`_HQIhnNu4MS{CJy\ٿnĉ'HU郮EyFD;wƍ066F7F_nlllJKKE90ژ_X#<PDSSVAv---Qj655&&&kx<ׯ .**K\Jl333a&=l]J[Vi/ -$2$p~I31cxQc~-I8</<<F_3L'''KKFq|0Lrrr?tM,4 Ǐb$%dCh lJL#ӳWP?C x$͢" +W /[XXܿ_Z##~dprr/2 pppDr{d&C> Z2+,:P?C x$Vwww 30ýyF͛Ϟ=$~I33dp~] )D̪O~y*ZR/ƽ܅ʓ>}UbJ`yfggN7] %a^9HO/<㽧wddgL0qBt ~*O?x 3"It:O~?y{{ŋ/$/ Z\fb/)5 ?hcdV%ҙHD?h:<=rkq~ܹwQӦO{"gLS޺ٳ.]5>qPwM;kC?J?p7:ՆP?C bP]]-XRYYٽS/aaa?URRj" Q(G>}zL%%~ݯd͊ /Jpp0{wl6M<18FI]@~j͢&ߐӀ~~)?'~ȣef%_x:9?<{T^eb$If+K㲣h;[0ivo;._ TBb^ӿO`&|Ś_~@ģ#?00PQQyfrrrzlyݺu UUUr~pqq9z(xpx ={zwqrr,SUUs_MKKt@F FLNѣԈd񜜜Ex~S7N#At`eS?Uѩ't!iƸұ#:g%0><)$]:ljQ6z̔YziSi^?~BVNFVNfTY]QDžKV^>Gq6xx3 &悷D"QIII#]|r@mkQ?K۷Kٮldd\__?0miivڭ[ɓk׮ /8x~;ڻDMȂ@G}Ԑy䭻c3h;0hԱiS􁣿u;/];Yb RVGL)J*=n3)='8}|P-3>'ZVNgD]VV… ꪜB8pt'NTTT3UUU?~OO&Q(ܸq@S+WfϞ-++LG%H=fffLRMMM?ttR[Ix' ]\\0$$[ ɂ>֖VܹȢ&'QCݰ*Oh4EϓvٖG!!)ߴi^{{;N?pϹ;]i&###ظ{n$nyƍgΜAʑɭ_>88b!ׯ_o``NۇROdg޼ysNN۷o(Upp0e0vL&B888lڴ ijjjkkx˗/>|] >kgђȩN ͪJ}^,yktu@<~`%P&NH$[0]l(̮Hݽ֝ ެ 3"6 Ǐ'3gf,((UVV,&~cܹE6''gܸq-ӧ &t6++kDeffqlvffs-l6~mRR`;&L@4~CNNNH?Ƃ㣡cS(~F://oܸq@={vݺuo߾[IXTTAVVV_pt:]rz=<<ƍgaaޞyٳkkk%@SS˗"VVSS۶m[ff&x0<[?XIHgp6D ob)a5-TPwF qYD!!=bرtI*۔_9+ yoeۭ;Q9"رcs3zF*۔ (A Gݻ_z$hf]]_|&"g0{l#D?WTT3? B ̙mjjnjTY~~P;!!!"EψGllܹs.^wqq9w2Wߩ~NOOr_|yȑ)SlٲE{;^xabbG䔔 SQ1Dχ>}:Iuuu:::/_FnW^lgsssdrbHFGGV_1KL&ݻ>rwCPJKKtttUn{{@HII)++377y(/..(wYYY-XСC3Ȃ;wp8dqTTԔ)S:$+WD)8iOP\VѣGHe2CPLLLttt|||rrrp8x .s+XAmL $Ch1@sze⇢1.}$j6nqcRGzؓ,l/ܶ\nq#够&_ݸwuگvoEZ`5aA9?It{fΒ9U3aL^ ^T¤&aO>};&OgD ~j7_ϩLC^ikomo]2bpgO%lnGhRӷ1~'Q ۋ%aux{~nǷP?C "T*uڴi3f"0k,WWW /g(..N5A ihh͞=qqq&M~zJJE8~={/_~-Pرc{˖-C;<oʕڹ b?O6ӧ wҥxĉ ÇŋWP( WH{{o[UUUSScbb{nQFpÇe]\\l`` 8:E?8prʔ)Ո~۹s'R/^쨟|˗/׭[;::8qDLUPP}TYYy) u̙U055-))AxdL&;w޽{Q(իWnܸ!؈;P(ɓ' [wwݻwP(4p #s߿cEEEX,T*|X ~޿?8LMMh4ZZZVVVHwݻ~~ˁ8q"b3m4555p%-- CܐsM4IC::OŪx<^#G@sssuRSSCP겲Ϟ=C>ꨟMLL۟:u|3g:6.cgg^GFF sAn`n*~ԸO:Up\D0mYU_3YBʙ㒪"ɁRNg#$ኋNkkug+%%s\\ɓRYYY0疖O<(**O1f͚1BL<q,,,EEE'OB#1gϞ)++8AF%SAAɓGd2,:`XvZ7?D"bbbO.~x-RuV+GՒY)<ߏL8 h-J̦XJRN"R__/ݻÇ熆oF0P;^ PԎL]]]`Sn+JJJnoa6U| Ւ8Kc$Ȩ2T98n v]E㟧;R'2!Hl˫9;; $ GG#Gpm4 JޘRA  ѝ*/zzZ*)$4tzqҠ^bN||| ؕdffh$l[[[' ٚ5kP(?ϳg644 nF~S{Hr@IyPTH5J9T+<<YK_NeZPS3/2l`0H666||A` 'ޑg "72> J {5#*FAtWʹWK@ ;wNCCCΝCrB *jllH"F hbH$GGGccc\p\<_]]-~bbb1Mpĉ} p8NSiTT(.ud`0|||x`Bz 3~ohhH$ڐŖv/ @yy9+%хAtY!dBϝ;IMc0n?k?~>ؽ ?{ U6J_=0 Wb/@ @ C2|鐐 6Fdjp8wwc*.[VVNo/&PsDTp3 Ahtjj,++`0jphR__c2b?xF5WQBc))hAtYRKP?C P40>>^R B #jSyL8Jw)ufDGRN@,R&&&aaaj%T5~(z8ubAy,!a tp8.khhpvvca[[ۅ |}}% 2yх %Z3"*QTS~@#zC ...qR'Yb%Gx|^y%mb)qL Zt<ږ v Ȱf'.x6cT4-d.koo 3wYdh AI ݀DGRNv8::v/ "q`Xx]r]\\:g]WWo߾urrZdҥK߼yԿzҥK9ҫꆆo":MMMfff!!!^F*C|dmYdBRWʰ6Vkfէ|?2=K||3*?a 8  "۶m2oݺuB'++cƌFʻ8~^rx-,F8{~3fLUUUff&P;|0VSS ?Szz:'ҁ@NwDP?/^\.w֬Y 6G5|ĉ|xxxӃHJO?,ڵkO ґ'$$^zٲeׯg̷~EӿUCCCQQB!kϥVZhҥKwލ͛7|󍂂•+W@UTTf͚,WTTܱcǶmfϞ%v31bu4K%8 9***22RII mmm| r' )m߿߽~~Rʔ)[ ׎ݻwڴiHyv/fVX ZW0̙3's &\ziGVV6##F3eT&^}.K%C x/$2^h4H=ՈAywwwt1cÕD~x3f"gYY> oEϋ/ &88xɒ%>| yժUBaAoVhuatd9<29m$9 2TRK$NWq5-bBLQHU˖BK0tȰԔD" v/ "A"LMMBUU郈M3߱c-##pB[[[P|!++CM:qſӧOϟ?A,''wƍ.X@H-?}tΜ9ϟ?}6FEEE222'O|ꕣ… Alc<looyfA-Zd``;ggg0/--}C4 *;99-X@p޸,ŋ͛[n-^Ϸnڶm111<@R ڵ0((H$M6f$qd[YuIayK" juo2`BRG )z_\.J]-  P?C GGD$}||޼Y;\\]]8第,@ϟ766D O+++{{{ooo7n000knnF]8p}ggӧOw|($.CoʩN. W&V6 [o5cQh-]1`ѐv0 ccc0dlll,4(:gϞ tF5C'zɓ''Oܸq#XB8`{\JNP.oJň?y5dy[@ @ C'O\v j~׌H*++u v[YCQJy\Xo%,QF%_RA[Z_Y\A kh-:P?C ҥKb~@z׌HBCCf_<Gˈ}S+; ~WRA.[\A\۬1 Zt~@ !BHHYSSSkF---X(oVRk[i<sK<67Z[1 Eg p8ү@WFϧg}>;4eSXC U| SAt@ Y988l7%%TO!ڵk(J[[JOܝ)**BknnNӭP(R:998pl̞=˫c9ݻwo߾wހٳ(JWW<`0[n1chԯ߷o֭[ܹ9sII ҾY]] :y$NG>z՞={TUUܹy%_˗񆆆4B:DDjkk;>_R*(ǡTeSS #%YM*&v: 2J I$VWWӃNȐBwߥL>YP?驪&'',YΝ;mH$^reҥį|_`5k=zcd?~5edd)**nܸqqq۷o?q(qΝ;kjjDtHHHyyyaa~`trI޹sgJJJtt… 9s(++?y$..n֭_VZZD˗W\ z ZZZ$%%-[ݻ<..Ԝ:ujjj*_yy͛7矱}5u** *{ܻhuT@F2Qu/Ъ؂:"3 Ô=I !$u60` ɹ(\s7(B?ٳ׬Ys}ƍ-ŤIY`-t"Tjmmݨh097UEU\JB1jYfE # p?\A>pž}4=P1?؜={H$d2;w&}Oz{{Y_#$$d #G/믿}SSST۫W/h]3k;<<\WW066Ƌ]ƌ o0,_\a!Cׯ}x<WTThii8mllL$v"hll73?hov޼y[lY~BGFFڹsgS9رk?r hxTh697y D .5 *(i4=RzHdޫb{說۷AZL&۹s;P~޽{mm-jCPt邗OΞ=[u稨Yf-]tʕx 2 }&''|ffX,n8??~X95ۻgյkWOqNDDĀJ?-=?-O*.NJK)y!d˜JPR~J,S_ :88R B9BhT~۷/^ѣ^z޽iii})..ǏaX|_~e~Æ VVV۲oߢSLš{{v,***--Mn>-O4UPj|77&()D.M/6jI璪7@"-]U D{yy8t *(9oYE)^<رsGFFFcjrY,uuuV>sL߾}L[ ϓsQт RRR~rryGի_~F\yȑ#}EEEk׮EtttO/XaL`:uo߾Æ 2e ʺۀF_+Μ9V7oMMMj{{{}}}##ɓ'Ǎ7`绺:t胇F珡ʻ+|gϢo tqq?FDiii6JԸ /K.)ly> ./TQQѩS';;;G_)ZZCrnaa&?K.fVTXhzpiu1i DHv{S ϥm͋vYhG1555=VVEwˋ-"NNNzzz,x֐9Z(fBdwp~=zĉ1*JZ:ujʕWq=4mbqUiY'OKkH*FbAAE^rat0Z`;Ve"#2U =ϗ&,}Oxm޹|Ch\⪨߿?JAAAmW;`EEEW^uqqȂS555^^^b5|(++ ϟGaaah{aaիW{R"s+W+џlΟ?称.߭[W),,ro+,'ޠe՟?r ʕ+h<׮]n%\\\Μ9oy槟~/~O:k.ԩS}||˗/d2@{_&722dfff9s{.]W5zCJsk*. +ӈILbAE^'1VXI}V.gF-x1:#BY-Ѷv;m1qEFF[nر3gܽ{鬎-֣ yƌ?F9zzz'Oy1cΝ;'*)a1J}t:}Ȑ!ggg. wy.\@ݹsu.]z%333|nLLoݺo߾رc{Wzzz...?Q\O4)((ݏ344D͛gffvs΍;E,]t.]255/]:tڵko߾8q"… O]+"""~ww#G5e2ٓ'O'L 6++ 6|fffhs߹sg|_=TuM+IέmՊk˜`򳨼TnL1+©p4PHũϢmFbY[[5UkF"t[{#Fy.,,֦/l_|y۶mϟ?Ϛ5 Ν;7n܈]VV.s?uf)ӧߺu F'O433m/..B|1 344P('ߝ8e0:w0B~ŋ666ǏGKL4V(޴iB~FEB'|R]]u֭GgOj<9jKӣA9Oo\HqRT/ "+kU\ BA D:xGцѼ.]dڴiK(g Ə^177G'e2MLLP477GQP"|gT ]*(::ZGG?~ ަh555| ^O +]ZZZ%>2?k<3j$VSbC>yH%)e," )&/QQZ ϛ6ƍԠ Pё_pر~~~:zzz~P(6lشiΝkii"0 ֭pFo ?#>>>k֬>|3a]v_:fҙTl2vB^}USG~ş~thJN+[Tf3C*F5JiF =$(ۂ|.U ƟbRZyN(7I6@4g4VMM#~kF|R~i>7mڴsNt?<}Z8?rr6l- ۷/:%[_~9 >Lr7|coo9|(Kҽ{֭[FB"pԙѵiBW^ׁڮ]ϟ2lʕYuuu>g>ߥK|彨BLT#DXTZJ}UTZ],Mѕ`<)Rϥֹ@W8 z߭ᰭaC'l s׿ @X,7H$B-"D"ݸqi>&?sN6mC 677˗/?\]];w,l.qFgggT\RR2{ӧZJk}mԨQ֭8q}ǣY,V\i``@ v___mmE͘1޽{x~0qk׮5111c*3?GEEȯEiӦ'N?e˖ltsaaifϞbŊCFEE)4P=?d#G 2d˖-&&&]5L#OTʚrjYfL~hPFUIbjYV7MVX Q98՗_-7 yjy:=ul`y}2Iu>;yڤ_ vrr%AA899y{{Ù珧oJ /$ gY>}b -GtRRRZyÆ R `#t:'H޾}K  x<^߶ӕd2lTrRH$UTT(R6 FjjjllPXG˖h) @up|f8SE,iEqa\LVbq#4=CP|-T$VYß~aO;=254,10,1SN{%})东(a}郋81ח3I9o{!g*j555#Fx'הś7ojZtةjī-ˊ yOgx?2eV]{DpQO=}bfYټ*LH P@&޻bO7Ϟ *ZW_}5yd| \HHȤIΝkjj:iҤ'O*/D}Z`zIb 8>4(0T̊9鳧N6޳".~nC#ܭ/ns;qXO^?@O;ѭ8W^YE)|YSç|sbfxa#퉹1FÇXsݺiC~[@ 4rx̧ 6*a%4- _zώ3~{nM ~$?sٲuk};=fk6V*Icܼ@~o8O5T*H$VV{5*XU9دz~FT\՛\;=Yo_s #Yȓ79oƢe rD7=3rrr @}L]S[O&E ç-5mKC <ۯOJ~:z>O%+XUŖwYC~XVT<==ˈLln8,,$-z~~ovz:3lԛuzGC˯}uYg~"|'N{@>?D}i'b7W݁vY}zC~ ü R8T*-((tpprj 6Jzyl~XpOoW=?',n>},[$%gʌ 1Ga61ڵo|?_xiii]%?}ԡ ̘U,v;,{5ax ]fBIc͖-g23ՑH$777'''+++ͮ Z!;;;0UYj1DZPJaL8՟W[!E#72Iao1zUnXG&=C_[%ΓՐЪTf%3Y_''ngp Ma nn(7 9 @~  6+H r +!dbg!?ͧV\ZFy^XId$94N6/K3 ~ ' M* +aEq|#a,T\5#@ۓ&LlZnL~(oJjb}jܸqaaa'N\d… e2+z|c5uEYYY{{{O=@ L0aɒ%5@oN*#hN*Fe|VdޫFD}50y!dߒQ3Ko>}-[6YYY:::\*z3gӧO~=d߸lvϞ=soRBPKKK~3?O<eO?'---ӧO_]6D"ƍ7qĬ: -,,݋'''=zҤI e0y֍+;~ @Obée _UwgtX*_~(뇇ϟ\իWncjjZ[[򳣣#`…w6k~ƋOd2.:\_~}SN_;zh;vE\\^I1)4#C)͐S=^+yWա  @z~F e۷oĈ(?FGG-Z$g``B+gwE"QtZSS'LpA<*qEDDF)gfZQ~^fѣGQw0&xT*3fQ~޳g^XXؽ{|/ׯ__~}P2gϞxYFgL֣Gad2;;۷9F%K~AAAn:BGiiiNiZK`DD*74߂Z+6VL&sqqBJn߾eȑxVtuuׯ֭[O<9gΜ G<ԩS#F8r^222zy''Y͠gϞ3f=zU|왍ɀlllvލZ6w5sL*Gp8'O^j?`wϒD"tңGмǏ~H$___~X(_x?_:LJŪdllBryyoܸ!_ȁ>Ϩ$ۅ !4Aa%=<(V\@wDf%:&ZB3P;4rcC \A<+ s{F"0Jeps1YBeC`{Ga cpsC)^bä yP\7谬Pg Z!DbeeQ^\AʫUƺZ}(xgbb2vvvEkT+I- |JCӣh]0 qC>Tjg)x.jѵmtXyyyḱB*xzz:88pL8ȼW  <@* ?H$hk<<< <"~N/bZ |ijbRJiFهR!TcJ  3@[WR '1_W1T(xnmW{UƯ+2U#ZkZ5bhT@Obé%U&wC)~yZ@㤘RBfH1iC)eՍ7h,UR '1ɝH1IjQkZ ?hJ{U35"(xn9ZD*f}hl k[𜭾с@~ha0ԢZqGvE/ρj1DZWP][-XƆm!*Da&+1b*900FAs˹-,,{}M}dJd%$/ Ѡqܭ[giA1Z-*x:@ݻw~@ڛZqMjQ\ya%]-J0IJa/ >ݶm|P# hO6;U"O [:]=_L&+"^%0"<5J稫֏^۽@5v׮]-((P@Obé%UL5vKdR85q\{{o_J #rp-.{v OI)!dJi[TLt_=~u}C㉴-kW5}RR '1'UJ;^^۽oϢm@[{ʪ<;R<+++RqƳh[XiV>$Rq6;5Cdc^LPA?lvۆXXXh<ݛ (QՊk۳D*I.&҂:Zϐ>j1DZWP< ?C~@['3Y_7`Cۢ֟I[ 077JIͱ<<+4EU+巧Njg}Enw%ںws>әMo\3H r YA]C -l3~fY.?_jMu=B۽]h6C;㌶޿`KV,?G~/nڷ=.:g'Ԣ0Jz3/{VKM^O=NOg&7ꬫK;=,1{}~Cޤ2S}߉}#(7a| (-5m ?̹n8!?@䔞.4=Юbk׮̏GI)!dJiF"/xH+gy$,+V'U7~ l^p;;eӷv7k/\ri3h >>?t g;=oa[v%H${{jM[w.((hKT$&Q̗+.!sͺEIPora|L_aLB9t1&=L!?GjkwE 7n~|~^j;! ]廽umMy 퉛[``G9???WWƾZK`DD*㳚g\gAis鶴0Kx[6`svI|ӹM^t?fQcGS; rﯜ6kŖhYW{ٯ,[,~}zoEN'_K.+l%f*J{[=zk,\b2w[>^:Cizp8Ha꿘¾hzp-<2?"ePeЛ43N\{É1O]]yQO=Y9wdto6}~ۋg {H 9qyo9!E&ۢlhd} sۃ{kr-$V[,lܴekM!gh묭%G9TjmmbJzyjQ\% iԢ0Jz߂c+UņR|8$)7~SHvo4z-G˗/uttn݊>| ///Ҫ ӧOtZaaaFdd2ĉordyyygػw۷Ulܷo_ڿ***h0?cFd}٩ [ffbT#'8?'HvѶuK'K"wTh*yŊd2Y!?;vlϞ=Y]ݯ|7n6zyy#H=ҥK˖-۸qchh(& ˗055ussC۳onjjjaaヷxeF|X]} .\x<|GEOTT>NGGÇϙ3兞ϟ_tEdd$y߾}ј.^~Z`KJJgjjyf >ݕ|s.]jiiG&ؘZ[[+NVgEJ`D_̮DzH-xJjI%gTu{yyW^2eʝ;wHDg5 ܹC*++Q?&&&;vBBŋÇdwX>gœwnaaA$?~ܷoׯ_͔see%[n?sӧgdd899y{{gտkZZ޳gO:z&?x 0''݂"ܹsmmmI$˗/pJKK=s51 2eʵkJJJ߿j* BYI$СCccceQXWW4-44ڱg{N/b^]كfϞ瀀ׯr˗/6h ͛7;w|hKڛ^e&&&^/{.xy.ZH9?1\ʼn->o/^0aP(DcחǏ_n:+fO ##ս(}fgg9|>|O\IIGtT၊dR+.^Gi9UFUɰJz8?^QpLׯ_N6 _9$$dܸqCsڈFO&]p\xްaLLLRSSH$###<-Z;l0SSS;wp:4zcYXX붥.\0==]~oݺJm޼sÆ ~#G[n522ׯʗ.]ݻ!~"_ڵk7dȐyy6ߴiӀF}СSNɿ ,߿1~9%%?-BvvvFϟ?߫WaÆm۶m(+WӧjAKW |Ps:ʮ."@vutUPnxxx,]fTWW;wש^IKEo bC;N3ώD 4=ckz'H.]4}q͛7̙3UUUͱU +#r_eU\ 3étL!~dUF|$us\R8ϼڊDfT9KP#VСCEEP9 WQQѡC-41 ˜P/נ777'00M/x?8>C-˔HwG4dood4Auu=DRWU _g&L~NID*-ɉL&kz DNNN^^^{W̬VH$fSH%BI:;;;[ZZZ>jb2߂rt bJiF'8F,p@[%< %YI8PojQ,_,K<'˂g s)$&J+?+hϘ cV [Z&riv-xWaRMy #<(UohbMDrsssrr8884PU[2~޽{seeݻ 9I3gPأGdX,O6*?w533SH={ۑ#GfΜ?TjNL:lٲÇ*aE :9*..S9?GFF/3?K$?o߿E޾}[绡mʚFYAk' T2ܹsk׮Es, IOOѣGMMB~{aRSNx0|r۷={ fbb:Ǎw}fD"|~~i =zPT~ֵkr0>>W^ K}}}gϞ]\?~̘15Vs2I s)&p>QjРAxҥK333gϞ} ]__͛}]^ɓ'oSLK.}mRRҌ3;ڵkÆ 4M>" ?߿'Oh4Zxx9:t/R\\0uT\TT+#o...SL.--%j\g~d+W$HӦM;wBsAAN`` F0L([חVUU?~􃇬Mg*(6!I1UR֞={𺋇:;;bŋ[p۷yĉd2ߞbŊ3g^|9++m4iҍ7֭[7{˗/cXSLټyB]cd_^v̙3׭[_Z%>>~ʕ3g(/%K̜9ʪEҼ/_>c hڵkH$:s̜9s/^|]_Tȑ#999~nnC{{{3gδFSSSmmm͛7g{{֣hF,H/N!PJ3&.!eoui GVPRK*I&?fUБ9#+O$ӂ2YIBID!eJj,"e!dx|kkkbH$kkkMB&Ť4NN(70Zp$IӣjVTT0-aQ'2x zy{{߸qCӣj榑]c2NgWp42SSS.E ڇj{{{YWC-wboܸA"MDNNN^^^-kvuHZx-e[ώD Zr-5xFx8տ0MVW[Ȍ C-˔HŚPRJ &?a$B :.agg%"@rpppuu-(PR"0L~F*IJj'@r<== RYmJKKwZ,SJ3B> 5bxxxxzzjz6RL!R|Sb*u c2h90i>JKb346J"hzHRkkkc2YA#P_$0"*kʛshmZLj}V.(mA ; U: 5TZ]"h ?w@ 2~I4=8*/UD~r$f1/*um3%CFR?mJJ۷###CCC---P}&LHNN b>8ʊ6k1ubqر={xۻArD/ 5߮ں簰0--{N:x`/9СCC%$${zzG.{fyq] oiiqO\\IGGfwZLn>;폚o77u=aWsppMN>'?_pAP^Z6N, OOϨNOOѣ>}*vؑp8T*4h?D5dyȑ'Nk+W'RZkϕhѢAnƍ'OLMM9##c˖-RӧOJ*˫p={VRoIIIR111ҡs~.((?4Saҥ[n]dInn;??_VK۷oڵ}2fsrrp8rrr֯_/)SvNΆĦ+\555sIOO9))iΝR+W;<<<$$D-K={~NMMj|>`ؾ}@^|!dggk48tݻw'$$H&iժUn \c+Wl6H޽;22sNZnᨮ>}YÇÆ s޴{C/{Yiy,~A)DFFƊ2fϞѧ˗/G%yo蔔~_W\PP')!G >\gݾf͚ٜP(^x!u#"" 333Mvuq],YRTTdX[RR""___Vk6F9ieޱcFEE>|bL6d2ƈ˗;wb$$$ kjj.\h4+**f8yŲg"f͚sҥH%ׯ_1cٳg^zyϝ۶mx^W*g(<0??L<QQQYYY^~h4jdZjػwoLLlNJt:]\\4%Mff%"?eddH***JKK޸q#..NyIIIbbbllKZ_rhjj޹s^k8/_oߖrWQ'ć͈R?!>toF |>uuww ,*N'sOY ,*(?28س{"_hoo a&I744 D_dۭV^7L=!|*44tC?5 endstream endobj 97 0 obj <> stream x]o7 ~B~A8N=l@u]؟?w?xV(0%?-eQcCi){S]wcaM/t!}{7gi~Ug?^0WF]\W 6"CMޚ۾a:P[~~ݿ_͍5v~..TɳȪ?ZJTQ٬>4wl\wun /7>7͌qy q}&w?ё7HI[Ӑ=.Gr2aHaK9>[,>Uc"lDhjUf$Z'rj9Xͼ$5"\!Y5ʛRf`bBhj~JW\P|tk]/.7܇yp)e[jeݍ%de- 55G0@hpj 7EG@pw2/!6Eq hѱaKrA`+kBk.DCC#3 J/lp`SGl1)p;VM0``(, }0P 1'0Xx4WMj3-80͵,hE:I axf]5|1K&;m̏&oA$ xE 4J1LԒ7ɯxOY|iGN8Xn t% ʯ ^f\[/{ KQז7 ;ꃛK2rP~K2fC%& D%%UӄUH$WT,+Q^L&'g:uVqa!"N)! ٗ]O*TԔg)WF!Fjp[#gS^0='^nDKw[ŮOFWHisQO8p.Yda>wJQoL-9eVtDpŐޝih 'Aωx @H+oz> |мŒmyIy:@-Gh# 4N:R= }FqypK{kX?dx[HX"9/bYܴsQ-}Gy2*`T'U[$D<k0X`^7(UQBNYš^LK YhEmW`HBMM6#iFr 65qdʳTv1Ũc=a#" >#?5bȽ$ _+&:#3( z{<pWO*&_BЇ#vq,1TpT|->8hG4]wOѦ ՎY/.3:q`2Փ1X.),!O < vW|cu`#KhGȱS) bML9y"u,y8O-I>5[ݝo/"b&ߋm妣(CXsܲ" ijE#J[WG/ⰹiNEaZ-z!KC•am.xE|=&>T\P :(sy5/ǝw8b,X.i}P5!EqMsx0l)x\o7(6(QW_S k~W?9ݲzEDKH%oL^7Q[JcL=#aSsD߰pu H$AMaCUD#.ALЭHoY ں6Ȧr VW:.XڅbU`x5jwrqXYb++Ӌ'raZc:mX1ԃzЊ? endstream endobj 100 0 obj <> stream x|eSR.w].w/9璋I4{qY[3U#λ" BVbwf([\3j*}gVAG3;?yy(JzIǑk/R'O\Y0q -XxE2w,LL\0~8/!!$48~H*ǒ5IH0N¼y q 0ϓv߯'$̛̋?ۢF)H`$TZ+Ͻ&%΍;x`/(}K䶦ƨVe6KClVJ=l'b>r {̳&!5_IkZ/D iΓ/f~5Nt/Yik hjg h A~`fEc9GDO#6KkkNFd鏯TW2z$0fΉciRdŘqT=Wu[Vv + 9xc/BsJ@+ ,N:TJf]&i 6ٙج,5H@!*Q=~U~f3̂9iLiD]ofUEʡ߯ïN^fU j-Bi ^@6KfJ u%\q"mtSUM^$ZQ讇R+H_%kÄ+KE`) 9Y:(!jBU\j̑Up%.p@ C-AwOvZ9ΚϤ[41Wfc P&jY*uGN'2S9 *փ,A]ȋHLpJi8A,٬Pj# նQY86iMNȗ Vp-WJ`v&#$m%Z՜"+պ3PjW - nMC{R\dNU.JVY]PjF~Uّ+7a`8Q,6HȮl~$$$[G Fb5s8g\1HZ?ZXP_{J\$foGN^Dd jc!@jqpzH;MC ң?}Pӗt6EלzffۓLo :V0fjj\1yTf̬3nmfJ:mm=WuvsY6[^:J`b(-fMj%7I/tCUř `CGoh3]ysVg-WOԋ 72\^6& R+ԧ7V9g-v3iž(+g>\ސf9Y_W+( S7}V?e WLy u͒efJ h(`p-M-gBZ_jV45R3JǙӊ'_I.[xک!d WpJ1*.O#É}%7jNZcwbj!_ gT=\^[ҮwNlV.7zN[Ҏj(Bį"czԍo&WFI[J ߯py${<Z(p BNjWۇʡWpyi+P>-ZYD(f%lZԪʂ+SYjR+Wp xlY v0y_}|Jn+kKe*ϡ3z>4*ќ{J@L<.ω4מБk5KuZn" Z_.'mEז9oY{>" +cVQM V;xWPR{#`L& fC,颹?g"~uBU33[[>ڰ`Lۯ5\n̬f^R+P}9*.+7VV>W.O#!GV,BqH\zIK5>: {_Uu כzNsꅝ0 TXf)Na?\ސfLfe\rW.y)O :%7bͼdYYm"~ +Wԥíi߬u͆SجmoL\{"dy(`b˥VnUZV W;d_;gN6]*ԯ.JVE<&~A&F+:XJ : _yz[vx>,KKO((Ģs\۰XNBWqabWJ-VRٲB*$~%Xx0GHzbiD6!UÅJuzkJ-tdq@'o>c"D~mY-J!!VF=t Y 6BW'/앳RRB-:-圔 JğLNWΨ}XٳΝY#t~!!!'7gn߷*i:~0.+ +WE;3~Wbbb\\N_-巯(/B,+0LRE>Wޖx׵*~5Ե_~T5; eU<^%yp"53qM^?Y1`0'`LjXpx&?Hje94,ziQE=>7K|Wf*>j~ &' ]ibiWNEbOޣ,Ͻ o#9%p:u4+Ų^_Gcb+Zl]*=@(ܯܽ4Ak7qyvWۏjN}󳢊՛})q-\C'y`ҡpTX:ATi!dlctUc')|:~n'@`Nș<YI_ t(߯+ /0ȥ%ar(FyI79|G RfJ񫨨(iR.ڶڅ!t Q_UuJ"D,N=ik#(y.8UUcx&yHOz[<)G+8D+Wo޼zkȓ픞Qĉ|wY?JQ_N~[_z+ ./zٯ2UStI=7EstTWuSM{C./=*sWS+ё !#.#ESMOHn,ʅ?q B;\?zSA!2 Y% ,.z'˴HEWULfR 2\/tI?]/¯m(-Vn!R? ./z<\k<5Rj/E t]3A@u~e?w↛aϑ1"RJBZd;R>&6j4mGXM^q"goY`><6iz?0vxTZQeЯ8jיg޷̋EmN'ԂQQQomyI[1lнtm~kCuFI\pdծ:L4iW`S#KH'Z9#|\] ?2 W۾7d7{K p EzXv Yy?hJ*Q_yz[5uڔU^7@ڢhbR}u%c4-ag)oEQ?lp@D~aEEE=^lj^Kk=/ OT eک14lS[WϾG2‰j:rM~;ntK ! Ԏ;>k, S"Ư͉}7˙yȣ<1[Ve lm_7<-"ll(ǞiSOڥ?b뾳ğ4-OcZDx8QeuJ#bRJGcu-FEEe.,k!$>!>>a6(H+IAծ>i gXn~g}" M)(zw_ "ɯQ:$0&~CE k8~Q>|BiZ#iyլ^ze?FQ0BUMU4^9u&ANw6G0 дAN\A>hP@U*WȮG6hNsN U*{ԵeEEkPiwEQik@ D_{lZtJ)KByhV~v@UgM}ATHE SMC tD_yz[lXQ58y"kU][}Zx­SO +V W[?qN+eSko8WGϕUXRDCګ_efqϣhӋw\U/g_LJNv9LtzG5ϲ~´o=pʪ,xw~KW,Wu}>IJrZᬉƋDW0J 1%߹ее.8 6+)i?% ӎ(BDt0ǹRzI)ĊVV dLb-vkTO&f4+;k@REG[?=&~ak#%Mį HD<]ڗ#UQT^ O#{5ᖘJVVdY9 Y!  WnZ|egs6f!5߹ԳqW{EG.Z.eR牿nH;W&-Y`8TW&&&fܹ8cٳg4E(11ob%$$n=МH']H-'"bu8Bkuh0𛨑_Me '}l'$"ےJumW}EV bcc3gFH'FKLL\|ydp4+^%$"d`Y4IA}3gΜ={9sH_dZ|ŋ`=w!/;AD_mūx<[fw$#%n][8ghVZv3g$}iTZ͛X7kgǯ〉y~UiTs.BGj=u /}ݧ*bj.]7eI>ww〉a~ؽoJeulFEE,jƌwqRcbbTWy_%[8`"D_9.89ZE/_EԤAhIi_!p+gOc+C.]ǩ'6`Pxg̘oF3gNttOӒ_m?vK-6-jU͉9s9+..cq;t :,w?F6p=#A_&8OkPt Z`+[~IWu1U 0n-0laBh~\?Hh=MƇX^9S|zhYEj̙3g͚ɘ$Z`UUřj+RA}hv0jPe+LZݭz˨Q_*𙕝F:ر;ήDLvE)::w( 'YxIXKƁJ^C,5!Uo2U'- s`:Q_|XY:-¿E"YKB%֢C 0^ί=%xDAJϱ* 5kҧߒ'I!Q+wos< lesx aǹ_£Aƪ݌ݽ(Q]جr[S JEΝ""}iHXEaҨ`P_5\t0&!50"P`ZDw`EYz*ѣ/衧x"%P_Uu ߇g7v^ťp 23ҷ6f Ԏf R>jrZhd+ BݾƖEm,eSc>gMff1oW}rW4J+).ױyZ]K[͚5 Pq1yc%N^Y2{5]Ñ-bχ'{ڈBJC?,OX:ㄊ_ Wꋜgl13+M4ukXk5%3ˁЈdJqW+>>>i"$[\y0+C֯=;=6uW~k111qqq~G$ٚ>k}5FkZU*4\(;vz7>^ د2uo~-Oӧ|׿uͷiӿw?ߟݷ8{{k~Ǚ}g k!#~u.|d7: [;^U@hH_huuO6}L@k7o[߿G3&zɚVO5APJY'n$NAu\ i} J4M:[S>uϱ'Wh7UAPa+J}3տdv*3fq˧Y/t-M՜ߚ9-DS r4y9vԛU/+{]7eohS}jn>ٱ$<~#Kڵn5:x罩o᦯MrDӪ})Vg犠+cw1V])fS:WVw G)S~ͥ)u.9~g{n5AگqS/-]JY -]2P_io L75>Bs [<`A+ӲݽĽ}7PN9R4q3fTi<^(<ǿôn?D'< _I$iXc/?T{]ffSzzKj0̇9 |^(M{xwsu[Hb _6ZJHU]ffêUu #ȲMs/;pMPzHL:זIP9^~Ĺ@#%~r7:peYLMWGlIyos!h[zdV,0|zFƮqBf޶yOg0Du:S+N`9q,Q-$ڵҐ 7#-< ólcQB1Z%m*\8"~ur3&Ѱkv.mraoa͢dg9xẂ^5+ɔC` ]v^(?{@17U^˱%^ԍϯVwk^ fQ9p!j~jHa^;pQ _Tkc [ WE0b>mOIm&}=A:t(`gA4N4'v*%,"\ՅҺ{?:ly1+_jۈC) iDqW=l|շ0wq0LH'|nغ_{͢TО6LdCp_E=Þr`ׯ.Ve _16FŹ~=EQ/ \}c8i1t~mi43ϚE(x҇)z띟UA9Wfvu^=fa~)z=cJ r_I}ۂz ZS>a_ygvy zח+ ` Ш"~ULVl",z5\j8GQz3 9.~E%nE&Bҡn bpvo~ ˎ# `VgSy; `+|W5]V m5;`_l\FZH~1ڼtZN:^W%r;6X~Tz\[Yƫeک"~3 DԻeҀ&w{W9&66vqpe-yu˧'{K.^ZyvîU%B*1x -٫iFdC]r`[E3eۻa|& EQqq񨴆mA4x:&~qYթO-l:pnޮv.iK/r-c5dԙgtNMݐVV Lf9qF,[*uk9 &8J{Xʚm^uE%̛_{L6]_JFƏN\)<|)M;֕(;c 1"V> ̢;XNt%JK[p<=ΡF+:|$U,VtھbW|@QԼEo I4x:hg}Oq%s-{֗I dՌՈ9>#knʼn:|^-A*bZj DῤvU_>[,ua*۳^J[ &߆(4z|YIQTEeU-}M)l{kJҋ\)V]hIlȐz9\rHtYr">'Vo>٢X&WeR7vq:=_K(jђoD-7;]vgxd#s:pu&Ki@#3"N(n4C]Js+yC=+q&zfPou,YDNzQrhCn%VF4zeًk;JjRs5N) UR*;z_Y/~oSCpp{>=%G/Tt}}6\SD6_zUny3{Tqv~̙Ɖ.uVAob\s/NQԣ?Uc;GM=~߿/Ƹ:ȩO,{ٍ:֖YYJ:ՒxUٗ_~ԳI1ac^ Z<&6[=<*EQ-PkR_^o}?S|O~著2؈LU6\ɑxIsMZ"_7bЀ\,6iZSSs/׶^/w`v#AGxY+_}X7t׿1= Ց'ip4SWdxY'W('&"B,w~E뮻[߿{{ə<19.}M:+oufq nۯĞٴWRﳍE_uCLs\ȴ6#{ւ9gُ~qyw[)S^t׿s??ݏ~1' 1끟~ԩӆkF̓qS3_yVV&m?/ho*12n:~n']lZ DX}=Iub"y; (kmY ^"EeKڵ J;}ZT7-bP}uQ%HYv(H퉆;w }λy~ZGw?mXZ]N?_߿_̹{_a+5)vٟ6ݬzW&"=ȩCb(t+ep|~u|9~,N}IZdӡSzt:pU:[Q"Wo?v|BY{:ח(;1ʲ779G`׉ yJ~;1>uϱonaL!_ tȣCEzL՞3[3ά mu$+}-_Fʪ0O^2UۼWCn|5H"[::׷i⣗WUZ 2vm?^nOI'y8ᵴb&MqA7#bO@dw=^o.W*x}}lTohhbc)&a"ۈFWKG_k.?R:q&uw3"jhD&}5'5XQ~}䜆ZϦ(iZċI[O-teRѵ#sי5xi?BjNOs"xIdCmכEDP_ ]CYB-O=XdSq.[T]F*R2EfELm틈W3@K^ּ>ϑgfCHAH#H㬱UÅJ,ؼԢ~_,H"؍HxCp }ȍ^9G !"B'#ș<vmi[S^G{?:q~Uٞwq,j  w^oR?Q_9[w+s0ª]_ɩٯvxFt"}@ RTP yZ+lf5_WN]{םI@ ?+<ݏWGmݮtER̕ 4-~efiTk'DX @ o11TspFWRvݮjsAC/E=E-kpUjM,K9n& 7Նk'a~e!܂KdMNvkg2$x/y~zyE<,A G-ðՋ̣Y};W h? ՟> stream x Ź{wYNAg0*xf5JTj|T⊾CܘDcD"񑀠$Y! r!ȵ.}=ͱ03=]_ULm驪VWWW_H u= ^?tpqQ r{^j<,2K<}a?Ki2*'}y,C1td/R~5LX}Jn:7NV g07S4  c6Yf?qKXLp0x-/TA׊e(L>M^:rX|T䤣FZwqґȱ#pUy'MَΉNU8*s-<' H0}hWq~%*s=hx3@3Je0>Jqq58W*1wR|l1ʋNA2:\tLdY;:5( P2˚B#0OFx%@;!<>]NTٲw@eVc >㞠x@5<.I :Fޭ Zog {X` ۤ2@1<4Cᡳnfr|0Z@`[xXM^3^nfoL:UEDV>ز9 mWHCg IAb?ֲL=ށ%-{r&y` }<2K Lᡣ5U@ćA.]I?XC/V4$ ԶqM ЎkdV:}|F#kpK%SOx<2a(%f>CGA#c:CxrՊAz `><(`C-{*">YB\DdDWLy|TӇkl $iC/m=UD׺(u (6VD}C{ |᡹`^`'G9QT:C @xl~<Zp]LgmUV>ĩ8gS >-7yp7EV5@,sd"OngD"#7ҵžEj_v%ѐP=80~w1>G;^$PڅY#Yy|U;cdV~h\2Y2<|h0CɾEOl`ޯ(~d/F̃7e7>z%M6_4 ׾ s`-#,|&찣aCwGO@$?2Pz0;z!}srLvWHۗ^<|4ѷYsBvL< / fG=vZ&2cj*Q>bc+Ǚ NtDVl$/h0DZR%CHw<'ڲl|8*96,xX8Mة,Ik%Vv@0a~l= ==݅ K~rKzϻ ʄX؊sP yV j|lAwDgK 9fd>}ZH|-;%D߀r<%"+>vB@y$d>c}([2/d>jB;AR@Cvy >_A?b}r;Qʋ/>4\"Cڀ|t)r'bT"0ׂk2<1-4EW +o|!r'8Gʕ^>^(|0 rf|.`h,[|ށ$]kw*<|G#O+^Yd}  U! LiE#ug) Gl{x."xP<~]H(|4/y8#l,IInЇvN$LUECp@Q$Xp\wKd*/Q֒2;o[4\ !H^X}30$odi,b!~2rVYH_8>aƂK }dW^rWF}- i2kAdEBއ u-APJy(.|U 6ʷQ(h|l _j .(4>4Y- (T򎅀[R9T>N`|(箑BQB.rNq>e̟A>(#"|rBvB I>ojJ$Y'C/ >ҕ2)/ >^12,Z>">pK&!/PpPGJn_3k(}Cٞ { +dfkh}+b  va}(r5>Tb}%SXB?w>F%>BG֩YtŇdIeW˕,>8쥔/AaQ߸T5K&CQ(zRfBj>~'&{_R+дGDw(a|fjLIx[u!tH݄)"%Ne<[C XlXxa'c?PR*>)`?ExCehB zF?aCBɭh%oX0@$Tz"fVte=ҋc**px"9 C9īCGoEW^F^ v38XM` :" SnEQޗ&p>#|/<|@83 e.c AVtW5c.>>BP1. .>(L^s)hpG׶p>rju"Ǽs*X]ӷ[.([&ɇ| o;Dkqg,,WwRW~x}u^Av&}[.I,Xe{xHJkǘ-C6Tb 4T:NCobNΈmYycG)^COuz9GEݯld׋' ;MjKGJ X_8|E4W i ek[`^Nq~t]S4]@|"nN-/_u${ڔШMoa[on G~w~/nXkpt=} <sk\tZ07q5GD.Tl>P`~oóˇ3rUԍ5>ĩMSe%js_q˹..J^qؘGao4GNzCN6}ݪopG,[N3RZ`8K3R b,|~Å~{ǽ}*W5]1nFۚPdͧx :2cA uc~?*X 0[kpi}~!ߒm^8]7`i#ӷM&{y$!OX}}dɴIpshy1-Z`Ѐ?@50-4YIWR>JZ.Є|y}ns\ Wy>nn LNc8gc Wf8PMQlHN0XM]~a3xAQ^ڒ|`QJ oo*#_ÛGTF.<)] -e)\ t-oQQjaq#X\idB8X>sS@y. =FJK)[f'n a[ ڔ:=m0"x4[TtNU}eyKtj2pߠ ǣuJ;A9\0 [}y4ڕ< :~`SB,F(-(PP= gj!szD<>;)ðW1qVMiD`t[ #B።ScёV2=>tXJ1_R:sʻ^&ކ3C?vw7j\Dl=bU/fVdBkȅ^_8fڠ9>D$ȇ7MW{ܭ t)5^ǝȅtikURqO(aϫPvuD3c#tE_էX~ |8cWC$@?ۘ&̅ _2h)EXT{ʼn|vc)}fGL4wxt <:0oHN2Zh^F֫ kBN瘱_ _'}Y78kZ}E歁%>Wkcd&߱W{!v W0uγ>Ulصv嚯S[|H#|wя. fkEXH-7pC]A$MMWv|o7Iх$ɮͪӫ7/^HO$|G6OB N@pT.?> +=H|T'rl}ޘh_P&z䭉;>\I4_eB 'j{7@Km\A$>lウ??:IAd.^:v\ I,bG}Bg%Mϙ}O]̇,w8_׮]yב[Ab1* ?"<{vf߱3XGow~TM}TGtL$*G?P\WgožO?r؀Hۣ7yFS@7fUe*ü6`to~hv8WYGiUb.[k+++kC /1yì \k^P 3~s]_[kY!h*0=&gCf"W\;qÇ `O=pџjʴ\3 $]u [Țմe5W/ΌhoKc5s^/՘foJ99r] 8*aެi c> >ty2}3PBxz ?|c>ZK7i6a}"Ֆw:IX=51:̡Jsfl[ vy|q?ͺ>?1tP{ӥ/0fsE&ߐ|x Gw~of/F|*mfgnJeWVF' @Sϛ66xr?ZW@05O;ʩ9QSQ^팻n\?H6_݋wåV #&W_T5'+Dǿ1X>T=n*>SUյqs693@kb7H 6pAML//;YQӔt"?Y05뭢d&q[iB |Lh}%.zt'kݱ?~ 8$U2ˎ^-J}[pZ-7o^>Ղr}e/Wp9>V\ljNMH sB!\|-<:.B'>%[GTG?V3c/Oj:ë][68dE,f|]fyva}2{@0և$\8܄A8jwE7QZ.Ȍ"49WL~OD!o^S X.dŝvYd%U9vYdHo]dD[N]dFG8a~ml;aiaEkFG4" YHuGO3σ%,"qxXlw'p%̇7 |s 1uK.L#݉(.|Jf#?:7v˶4uF]A"p-"xρ4~y7Akwf&QPdwg3@ ⌖PmvWpzSZ]` ֐N]> /StructParent 100013>> endobj 103 0 obj <> stream x]]o6}ׯs!R`=] ȦMIS`B=rHPw4h%/yymqƙؽ6]0o?T%L ]mw/?է*Zۇ~y}c~:_ٿ~1g?_sc\mɴ>R)^^i6.1a\ٛ/}1/ sqaA]s{8Mn͡kL9W_T/͹sM.\}\ma\cH7ۦ.NL'|{1)&\Dcuy9#K ۭ_}lR/KG[#ɰxm望8V{ؤ[BZ5ơQnXZjH` NLGr7,U o3{6>XQ־~oG_8ЁW5`'oy@h<G!.ycScwܦNhS:Z6u<@v3is #hWK@]u5K#EfͿa_Y1zr#+IP@KB3gSCcԹ0v>8QWP]hEg+K4E&_J=QW \KBy;, q@#Fzkf()y捞\9j~hp70K hDHA4Qj4*/Ց!p3 QWjBA^ap3t+j%/$lDH^+!HJ a~iDݍW5 n+J'D=X5;Ei 4;/Q5  el #pX yz%z( >,aPA;FE0"eC{L6 en=f =\U=ialC-X(QW"{ މW_@pnǼMpe.%_,2Ԁh:R q` A+v H@Ċܥ#%0gI 0: !Y"X .&2`9:Ud`GbX,jгxznJDzW .4CQ|efC9°fbe Cut0`DGC5Veh(@6]kք(mE.Y`way1R/hĉ O ~;i*Ю@x E5%CLP/ g"6A_ 8"(b cHܳzaFfpVv~a><.ew&Nnu15BmQ"Z+uhb%nb%de Qq%E7b?-Oϰ d`WCg0 ailX񥔾b ( G,^Pr=Dy0NS/ΰzZ3!|&Hǵ`-h*ޥw ED2uLɺ6IA=/UN-JCYLZ)GF~P4V/tR!wՊ8"byAJ>No"e|xSAli_ʼnG"Ϲj*y N |~ё'{dδ֛9Ac`mW |>hǼH*]6)GNN=!GghE5,QicЯw9xwjӱHQwrW)ߙp㍡$9 D0K3,^L Wi{xU˧ٴ L%4nIs97fk(4f C%Ed#pYījh*=DF*'Ie#',6uMnԲkpi<A;mL}3 *R(Kȧ^IqY8ceў<  暷@Ŕb>iU \ᘗ-rM Ȧ}xU]<̨VS&xz,()W_\%,WDeĎIʈ?f]pxIO,VxS+_^ \in1K#}±o]70!tDTjbpb¿?ELnv?.aɌ"2x'37nʨIzhV#{O&vtXJ|EVԟCzBAK8@ ^!J Ȭ"K 0lKi ?8u4/1iX v]ԭzytzOԱCvtRM[s#T x5_>o+.]1>ַAp "j5Dp ᶨ!_ @u  5'kHvC'4Iٍz l2Tov6]ךni`S?һ{w2ׇ.:gsHٯ͟;w$8a_%/=Djt =~| endstream endobj 105 0 obj <> stream x]nF|WsHYku ,ZqŹ(:X<]&9rƜ;5=ƚGm:o>_mњ໺lh??`>_P:w>pffm0/.矾>\^^ƚ7fZWgcm]yor۷te[/.~////?﫹m6+sueTysk3Lݸ]c|g?q?KkMmlcWYPEkknFnƺ 'ࢵn>6&9k|֧汶5k!+o*B# JecPi,סrϯP5*P5(n| (poتphvU6\A*wWV z>fޔؠ'<{+`U9s> Ag8@P ltŊ>D:s8>A]ƀqLt ߐJ"H~dI0[.eMvawem  ,h*`z5ث V:<>Ѯ|d&J[ <xrNPOEK3S5H6`0Ge_ k'qR\Bt&\(QPDoAsalG͕ Q6BeO&, r G]4:,pl`VKm@TP;89T5H9E2|ȃ." AmSH::KbxÇQ_?xbpEϺU xGQ'@BB|z>7%ԀNؕ u謋|T 44$CE59#L 2 ഴ=4: W{꾀aEn/̮JzKw7)jκKdmJJ [$\3GM>t&zYvi!D6 f e:`"njV`H6HxyC:P[Cmy2jNOtnbbwC,$;FpaUAZZo`)͛-X\ZM"X"@( B߁βѶ޵KF4SE%jNə8?u* sô "4aAٽTF@*^~/P譕T *Ch.M4ԗT1 kq>_[BT/+Xpf^T&ch}Mx.rb(ǑW0ѐH%s'&1ȩXGNw 7D4 H0޲/[Z38֢]2^y}^Ey= "@H_5C_MsAe!d&J1gnk-4xd_G3|~^,i =kE*K!e`K79f1*72$ȡa[ Ǡ9 23ܨ* -kt!`Q~Ε Mݷ+5T%XTrClj?T2҄PI*OBd1f&>|YATw g s"L<=Ϛ0A<%]2SERW@Q)ͱۧOZޏ' ZJЧ-EV'XaĪ GsY9=w1Utj\7,2M}EpQ˲y N3i&!NJzNmUπ]&G佄x D꜉U +.t!.+ʤ:,2B\bZLޘ$#5Z}zLb%81x@1uS*fc:X*!ӚfvػG>zגʆC2Wr1QB"#*" N4qhcpO-G'P3._57>#n Y"ҹQ]U]*3|e$hg˄tKɦdͥ}J J ZS tjyӔêxӪjwŻKaM5>Fk˶Csq7?=|,_ ̢6hQmK}㌳ޕ]aQϓպ|)Vu TG_oۢ~M lܢ8W *tw ₊{;{׼K_u]kvQ#Ծ轫}Ym_zR<Ζo?5ZﺶBw=?Yfxjv; endstream endobj 107 0 obj <> stream x]WO眄,SIL1*h]lݙ٥%}c vqQ9OC.;wgZW4=-, Y@@%hH8h # % c-c_ $Yh0#?V0 L ͫ-+T䏸WX-4Зt-+LXǰ.+l镾ǩmao`%7q0; (ba3R܌B/ \dw4q0-QxKg A F3454V0G~6 *Q*NaB䏸 0PO#? DiWrp5<.Lxp%GmQotFղPOVS͔L iL|(@r058XgШpn-YHЀUlbq)*yci蠖UA  m"JMnm rU\ #ڕlKx3C-Vqb8IWQ/Gc+%r 9c#@ q„,t2@%h{_XXT !ju᪘XɵZ_ΘGPw)w't%v{"l*zƪUAP޾iIeMSw :J3^ iyP3@0ӹ=->TӾ?Ƿ˾8`u'<)}\hh^z(";6빊L{zu&X,Z I:'Jڥyvi`%WħF0kI$ 5&@ Й; ^XI6Z}WF8yb f Xe+f)v5YEE'\Zo+APQ50!5 +YOXYzErK0tn-ʽ5 5tPEy@0NU)tR@mm]~ ^ڂU[E-44pl?}σ1 5 80gZa%8x=}56pj Ojӫ 4;V ZO2s|UUL,PiȽ2Nhv,4rh|Pya9H2@Ey4Tp2Λ6؊}U+pdp+[ GE(ņ`rVx[-4WӁ}n$GhB'?WIU$Y@/ǭAХCZ3Q2sshԳ?4U}'hpe 7#EwތJ0M\[ϸ^_U"fP qQ8-zsTQ&:JQE?Gv rUtDHWw~͎Zs:nAA{]ziui0gJ%ZPu<&tU8u8j 7…/C8[C {k騊Xm4Q9.tI-e)]sQb/`ψpc| ToeL9"7…!-6UA$~>:"L.>:"z?hR_A?*ngU1lt S+)g^G֗F. sHUGAk{x3%TBY' -ʨ`mm ]^ _<05THƴr(A󼒮8\f(zd&PX%~fH<9 hܯ**U1hNL6kvIJNl,(wxXXXQ^{d00Ӛpe7/Êy(gpwj77㙐כRxόT #VupaVu+sGURr!= ;Ƿe eOgBBIFd5xTZ1_1[/gҚusxm1c1KP!H?^7|MR61 m΄cS\kƁEarx}L\(guoL^R_hԥ!wRTe2 orAt=wP3y7rPi[Fn $u=CK.AGJje6m`HVnmNWxK< bG* Ÿ΄ǣ7vɞ!]lψӾ#bqr3ujl). wfUЂe6qA4OrȾ]`ώŌW[ʧ<4 <#hGrWxZkP4ՙ-*R 8\Q| ,H SKvTA=ޟ"v:o*8c&^g>+‡} 5eg,FnjJNӱ5rH-viDAhdR8%f] Z[ fwol-ɺ~ZOP` <=S;zz3>ߙܾ>;smv9c-vт:ǷVsOv?F3|'uOƇWvg u{&=)סϓ Sӻ\8fݩALb|=-2xӣIj*/91r֡Z;.ܵ`ێ'\Xɵ Dlhd5)ON kq|cC˻V>ZUd 1d}{KU,NAskb][G?aqooGgKU(#.o@.Z#KGGW_O $/4X %R`iڅ/ -6xnB0zs,j/{L֛n*wrggf6 >f;=jViz3ܩuqLOлi j*!YG>8kZk3 jc hWgǟ#G{Hu ȗ܃Աm< ~+u+(=l=(w2fxq#}G][7B~_eܚ3]I1+ָ.f,h d.9 Rc鞾U6X=~Y³{ޣf8{*GRƹM6Q||Bь:6 ,ÿ[‹wt`X3}J^zqXtI/C1v&qVu,@M;Fb7|h'U5PYn6!T}<njw.~ }Ǽ; *;\c#I+&ץBK4NEx̉wzj*nݓ;Ox]B ?i zgʶF+Ҁyu>.ˆ+7K2'bGn 4Er̞b8|g2izw`Q6/Ñ{$vڋ z3pJ^D*w`AKRn%*PnDPl_]5ϟ6ZБEDmF+ ב8Nɫn[V$'}hO~OlRW E/pV܈c)e8 Lz ?`E*Y?>[?pnRK<%" ^8b9x^k nLSIIxۯqϣstDRׁ9RF+VRrkɍ-73ݢch"Vt1./F%|:=8-#"%/~r^.aʓhFV622A-XJӮOgӻ_XxcS":nfH} ,8Ot&f}{r "?-H %_cJ z *Urƍ"jFyBA܂\&ʽs'6jFyr@FnY.cf+mq ceQW-ݏʈpN1$hVZCr-E]|? ˡ)̵kH*_ӛiֈ"~W}*zMkE6M OvK 4r~UcU&ʵKrKQG"3_:vT{+L5Z`&ҏY(Dwc_no-fk D,sP/YrKQ_s`OԞAzsK 'N >I $wpZ&@0`6A.bd5dٚ{1PDn).CإsZg OP5M2~9c[p9|K vοy(fߑ[h7a d|AlF&ϱr?mnmY=ޅ̻ r 40VTSnX8jQ䃣;mֽ]]#(hfMJCQc,1[Xq i+RW9-Ȼ[DZ#f"ZA0Ӊ]# ̧ fI^zJ w⥔Xke秧N_@.K5S{i=\wP>}L*/o`A5c,:_j/!ZoB[C(cESY>gqJ{%wBg'.=ȵ%=jE(G*a[oAs,ؗ~_esrVhX`5,hL1YyT'k ٣FEzY\ʧ}R9>${V'= z] HƸYGRZ桼U!ioS36!\z\ jOKONлU`p/?r2n&AOǭ Sl-P)i֢s Z?>i5er $! n -/R8ϴ ([I%dR#_(|*uPҸw`TaN Oc?o{A[ yO=1=q6Zw^qUp- ;?5Rzwt x`+ 'J6Lgl$<6ZѓW#w.yk ^s:l=&h-9 fgnO K请u*n݌hъB'V4uM_fL,5ѼiσaTҾwloҐzrѢ}m -{'¬lx΁U`AZI3im^q )wi 9oC s~co)BmYJ^ ^={0q~p|0] :|H䓳| l{=[ QCZhZ:w;`#BE?]95=`@?= +ҕfH23?+?ωޱ-W,2w >[ f Eqqӿfqs{[Lxxx%dEŊ^ևp:F8I)i,_x.;7fCن~E@N۷i /N׫ P1=4s)n>=%9m82v2' gޱO/ǣ?{9x"Ci>/2 q]tx^j%xQy5YԿsK+[( !vuO@Qotܛ(?E q>'$'rO WYM~ כ!5#.4AH1TOIވ˯" ؗ a% / .&`߲$Wo:d(jA-%͠ -@K fyQ.8zyse6)iP4@G ,WK -v} Y慙Pq7 2y-Nᝇ[Q$r˒mS?O^|0 0RnCa+S.ܭV!z3}Y`R0HgF6"aZ :  VWWB'4잾qPU윀^ݞc4EI,: "I3PoZSuLu of TźA!-.)&hu@\m]>#9B*cէx67;c*HO 7K1!W4tPGr\*' Hk5`uuu(11kb.`}s(,\$VAA=zZ|S< (X]]`` PUҼ":1`h]9.ށ6n1IPw z Wx;\`*N%(9]xς@2p`y U_uODF|-@6?[YOdkaGBtm72A Tx=r=nTwIp#\0^IoXcbNhL!QV:&*Xo䀁*SX<›%5mP^ Yb5N0p` )V¿$ .A5sQV]@ A>T¥z:?K'j%YBz i%CW)'MGQ: i[ b)3.BaȽoEtXQUs-Oɶ[`өyJhB0j@-kk[|\þ2J bRڗ% ,KPӥ%lŔq3.Y\vHURRᒆ LBM|EvEח=:'iJJ0fW_DŽ&XU+f["+>BQ3'P.$ I9 g`gx-E5ap})m^,Q&b?,':Fh$90{(dCL7laÌb@N3ft'-R7T&MIoмO˭MQ,Gx^ lJs"(W| P;_Rif[?ςb.zge),wG3YQ94kb.@qNE#dV#Pu7or!1YR$mm&on͝l,9`r)7Z$̄qZsgPL#{!h`MMn}'Ţk+͸b$[@^# &a ,`cm:Q8H9@а JNx V3@PH3J73y(\A~;\I[$Yh]TnOM XDjp^S'> nQCɆ ۇthy*)6Qjݏ <f`Ѣf .!4iYMTsQD)ug,,М*eE|>`ͼ)%,hme#s+Z{QȆ.WpM('X\zL`pMR(_E'T*{y U6G-v@29+\P٣j7C 814A&͉hM^A iZ<1-)$PV`ࠆBn׫PtCZߝpU_Xe8>u4PA+Z@r!'bQCغEבmŁc[J"7XSЋAXLY -U$̨& 8|F;<1ػ9`gPOI$%K,T[Np`qOFF34yt-l/Y: ,R8ȨcB$ 8jA
    }TEB#le. drěT-1Qp#mc­Mq6[!'h`FF6Za<^zLdԉY? S7!E,7 3? ;(!-Xp0/oCꞐ"Ͱ^K 38Nj䠑Cx1oy V"|o Vhd`njxz;>4_$ q uMM_^ endstream endobj 108 0 obj <> stream xݝoTE /"UxWRH ( P($jIDB@+P+"UH Q(p =3gcNv˜33|38C^e[;#&$γu-(s'`B٪&:twe7K'3#JȯI$%tdMp5u9ňF,֑`Ԣ}ҭ d +1O#X[HLgoI^U?bD%b8Z?^/c:"X{IQ3ҝAЃNj)9tƤl{&'Ι?5Е(vaLY%6QQPU*S.InH 4ER!$v8W͸Fuj ZɐM]^9*]!;4F3ƝfUdZmtLS/͡ܢ5g(x.޳o2h+^"-BP\$*CithV9r- duM G lIW ! `JZ"UVphRe R:tkB%:>mbq΢Vy!ؠÜ!!!rPDf!32CBPّXi|ْ%5 *d\䴻xbŴHiT0.#\RIaưT.'S<}yL0:0+U)Y Q:,krIvMAL#kcM'aUk 7#It6岯u@vH8a.t@Lwi`K,5TreC&eS].?<G\ b\e}nd )O]#OW沖Vc(j.XB*#,}ީi%?]uyT]0WHpfJ49Ot}Bsx`TQHz2{`5gRuXuuq3!7$k2zxY[. }MK 1Уu8:zg=vm`=>Ebw.bzfy;3% pu h:ZX鑪?R P4^/(jye.=GR]=dHu*&Z8hТݷ|&2M}Z^ .u$%.$s>u,v9]RI~#X>bwɴ!^X!p,OP<{|g 9@a#]똬r8If :,dK3*sl4C`N/H:#3MX (2?Ycm)U``CYptj*4*0o/u06 s?) ^eQd~| l Btn`,f1 ,^}`+?d⡡\2[MCF!.#M6P,_0PZaZ` -6[PߗZKoAVw|ۂM0Z~hWdaF뭢W{Ќ6}Sp!_os9TT n2>dOI`)fTr238ňLTz <$BFw\̐AQί%W]5W;cm\AYkU|>]+v+.L0 gy{cULn>Nq@De̲%ZX>r)L5![[OXn0}.lJ"rpG. *xE1=RI6g PA4~2KsCa$*Ed)jf{Xiѓ/P{5wj4 endstream endobj 109 0 obj <> stream x]WZK͟Z7Jkb&1pUT,{sf: k%{_ny}<|pHBq2W0Z`-@B ("( %G@ ҢVC [iWd C!O:*H@~kL* lgqgWwC{wf+#Y+g[ Y¿جǙq3{鵝cʑ4:W`_RFh&Cֿ(#j 5J*)Xn$ߕ UWwwI_+T MArt}Ak;qۢ: A䥤WJ[i7w+g@gfk'DZiGwRA22[_܃&m!=Ro呪y%Ov>nt\ʮo'G _Xو =Y\a9@Þ5R =3mG@ڕ͑^5@/-|>߬ )hhEY{&ȾiK=3k-<$$#`<(hx)$he$Sd`w?x45jeI^NU$PР4leZ <\z]c)@/ʢߦRSҨW/n&AjJS|^nQ=*)3ZBr 4z|$asPA5׮ogoV&d'٥` 1䝵uBΕ(5Lkc %4PJv QX]~י(,0|Mt7Sf\Af?HS9^d`9۬S4v9&Agfn1kGۉou}3k:cN&"ud+I4lfe74:A *i55jӢe^2/|3z pSdEL[,BZhd(4x=owb|^R2/`K ?Ӌ-,9ߧ5uB֙ rt 4yZu%jNA_.ve ](h tJu.ש<ɐ+~42 tꅑfpe+G8YDkkT2|#J?]ƞ틹nXenl EB |OA:g/T߄o@v8]:Aɀ&^HieA C;^xλb1[ˤ;ScЛ;\.?27l`iX,iP/4yT:N)Vxi'ns5 z‰V"jՈG * i`}ߛ Q&za{Qܡqɑ߁NNϯXUA>?{وkޔ h0`ϥ2gz4kBT!Vs׊6߽)#@+Pq]Nqy b ksr*{Ɩ Bߺ\I)P5d$Sb?y\:Zs?XW9]άB0O|soB6PŠ%y ɉͻ?aXW38H9vw7ݤpMfHF-|4544[skދ=#mq WvZpRnСCS㢒ߦ֥X&~_Ay[2,D^&^~1LJ0oZp&P^X[lt@ξamuk4}M L\U7r {* dÏ7iA5P`5,g`_fiZ;%oS (h88``ӡvivs*i}.l-'\kW]M>OmZTCMnJXӫ.@fY4SRMKu t!z,܁Wkxe|b> >xkz٬n!a/TOb-/`vE>)??H{,* ,5g>%j{ [ gRڴ蹇X0=2wetP寰*@!D]zi9.y/Nϯ4G}d@JbkYLFq2ƫ4hV 2~yh"Ԑ(>S'*P6V38 R**ؖ'Y&Dп݀ {+xе<ՈKF{4FWˏ&GoreάfSö!<.``Eu*NVTB^\]46|nJIÚLNmc j.{YӘ76W9'xNFv`B ) $ߡ!'b'aXL/6zCc40Q:Mo!e&Ƿ# (uѦE-]vϞ"^Gc:ˌ%NՐv_g\NϯG.c4^yӡG>&vԀElVBU/^R@;5goh6ç0OϯWcL\2r|~s*JozV G sftaqJkde\3eO?|ZD/wlF_-ijfUc=yNZ *$!+,{ n{_2c-֩~R$2Ö)?lB@լbw +HVVcͤpg25IErxޡe4s9/>) ^NT)% ׹θ}1;xfДbLur'+"0 UXCr)^syTj[Գ凭r,Dzf%ܩ8tTK*qch(>У;/DM<70HM.p>w\\p((!2L i`DݗJжŇ`OsJEPڊ7A xBsW{yE7{ixh6PIsٿS$lV×xLKާIB0o?cYЬDKakpŕ9F+rB p uq-q-Js w&`yɧ^ȥ[Xb*^ɀكl͵Q}9qQ>jӠK4"'DTZ}QXZo4t vh@3lYJDڨ׼b b),$cwS:93g.۴0Ȍͅ%X]@nڨ睧7ke96*=ˀS2cϐĻU ۊpΞ]UUc:m[sэ2.ׯI,KK#KslZ',NEc[11~WRHE d W'(B>|x?嫪:~tN.۵ȿﾭ4~cJ%(#ϷوlROI8V_ 5 Ĺ BI.+rg|IBBA%YUQqN NߩX6n_;s{GئEmتh{2.ױ˭bK#4+f5пmm6ٽq3՝YO{uCh!yj6q 65C5:2Y,OnV j1l\|[Gm"2 6{;ḱEtf: 3lJziMGFxHcŭsS嵐^2FW׹qq.J L1 kǏ% UQH8a;~rT`wr~֥(;\Jgkvrou:#ަ_9brÖ)xe ozlZޑ@ib,ru'+QsR5]_7vQ"}BmZy>{< N&#!-b/T% M +qAxRcPZw$wS$' MBv2O ۦEkudo3umc"b%f, eb'ծ}bq^>>oܟMT Y$G $W5yIK᭾:`WZg z O Š!wS˸\)E{~Kv!)45uos.j'f)?W1X9=5uu"*>ՉPI<-4 g˛S]ah6å$8\nzh|!mV5yupP-yC.*.b($S#5SZn nӢ0b "v%s.СC 6 F_T`p&8l lj̱s\:w?~4XNآ3K穂qQx܀7`84`Vˌc?qq?IFk#%\SxPS6w2 t⋝b t@eWB[5pd:RI<α z424oǬqA|z;^uNb,a-#nY^}˻7ϐ lIo︯WґJG0}!dN/k/Νflp%̮KDQ6?Midٓ 悛 ]ݡjfG vDr柸X[acoyvd7H\Ni.'J#:M=I(:=Zl 9{IҖ`Oro(ZlJ*nf~]7wz>Cʴԡgc l!}Ӌkz)g:O wf2m~S4w\T*hlމe4؆ ᾘ]~2VE<w\d,R4dO6e>E,:q\OKOA]DQ&]r20+4cs>wUߤ_9 }_'|]{̞ =e2e_v|>{x*է2#!/QMg,,^?\aQui{n#h#1~e$6~IR8.@?gV:,x=bb+"0܀rHa :T4E:tX1{ZGF^\[0[qcGeVdoa|-2i?I,LenQMa sshx 5gvJ9V. WR`k e'%L_4" {vժNԸGc3_@8B"sI-MXXZrU@,5DX:yQ"RގQG#=P=П1 xCeC B|*%/(M/۴pWꆯEIxWPr_̩4bwe^jPٙR FOi?v}|BiΠ2{+I}17gRG?fCM MZjbyjͼ)cx0l ~sO pteW=AA4gߎUBTÖ3qFD2?+ N۵Z>z?4R.dJj;.F6Az9B(UoHOe5Q+&% #j,{Bn"b]YU/k/guKﳡ/f5o:|>oGzv,D%ЭW z=١o&K<̟Ė'9f40^6 Hֺ` H wv葯\;Du됽:4_AO]Mʨt&0<11Z<{ }Z4)Jb2P;xp#$Er^ - g.zܡJE =q6b}eߋw4~`y]Aj| Tj]2b2nXv>HwZ3s9E-;+қ`{Mռ:W\ǟSuH6@J \d"SJC!OC< @3HH#"1W i6XW:u HB@rHJp*2OK9 ՗r |}FqMo\.o='nN~3UzV3 Nv94$f ,)*ҩe25Qya8-ɜ/ [hpyMlFq _w\[+aŪhخ cZJ2lφޢ2Md%sh֧gLAW#W\;ȸH szeXǻlv%'NآUKVJ[niQcݞ.]b+zKOLM+D.hX٥dҼ{lIm$#8)w/Xb6mxժEF2y7%f\B +Ϲvl0R|j}lڌNU ^@kayM[PA:]Z[cj-x% V(%VBQCphIwQA<7 {qdסs&Z幉]DE?Ӭv%3oREjՀn5L8PߎT>w.8Rа9،LlX+!*(ή9{M쿙E hs@rX$VV'vX+7EÂ/Sq *h80ӯF-سŲ߈ (i80!ږJ-Sxs x%j,vS@Nd[l.l* 9UN0 ?Arvv"C:ѬDڴhr&Oi;[BqS҇["-4Eϣ~@.I)߈M,69|qJ'HXG586%c\s> h ΒٳOfϮT Ԭia <\>Jf/}Ul(\S ,l"gYz|SlKH lj1w% &Q/K02!oceM2:t fjY;~<>I$}bC4]x%?MMCF{%$e%˛63v y!m| gW=Fakf6AJHCQ`=ѯZX~-beKG?w^,۴y#o)[I&p1,0S2ɕjR¢)ߎXfֽN88#XGZ+z)]BzC 鑒r \]?V:HH^'es}Q#Re!uV$Qs- W`>|󭉰cGˡ#GUnp?븿?˔P}Fn<WA&C5D[Hxm?F&G1o_:è̱$ l2X1/!Ai d`^dwT,u9 lDiDoI1oYmyL}xW?&t+GIa{(Mn SȜ]\^\tO]M"ӟForR2{!O@Fdd/ktf= MYNzyC)h>RCTPEs5V5סovG&|829j.*q&V>|j.bPd$_ I DI齌ßO̾b)8I)C v^<1[3s (bDhQF$צ쾜v-aU،9*0X䓮* ;6o$Sxm4JS3X}=&YG^vbr:}~yGh&p𿃮τ~毹 JۦEU{o~<vhA3K eӐ~Y#R 4Jp_?ڍY:sakpr=D5SeFw y㕑`쿺W#_:iE[7o~}zC2.o2}}C dHv+ &j_BE}϶[q(٢Z[{6ٷ{]&YOHo0׷YYKR +#t.z:^ ?d&sŭJ0EGbۛZw}i䢘x +ăK w ɚn#G@63|r2ؠ JSokEp"yaE+VI`KGL1y=nTiЩN;~5i+]6߈gluأjLǎ^P*H0cW!: LfwKĒ:zoE6vجUXCM%2MBYYPpsiBWҐZEҴ:dGG0ˡ9A _~B6-B{=.lrPk<Nb3-(XyW3:&o'4-M6-[båOVњ8bq Wpjg 3+xfl.UM,6-~ :(Y4lFؓN=z{E:)J gV2=|>LPKAK5p67;8^B#Q5Z.8NkKuɵVKQXV$l6uS.,ޅE,++bvWT­N ! nr4\o{MEh܆ ґ\^v}؊{'#jV=H8) Ю Ezrxn"r140Ƒ[N)bm+PfJ4ZO0(e qƽ7MmOSdӝ:?1x)lp4ӯ1[T+ 퐳8Ķk{sb;:|$FBJwӹ{Gb$vЮ&O A)jt5v,Z5P5PACR (gYӪ p}2M߳"85~̆z@:_rg(8%k_\PF 5Or1| 1zH_bD^-Ԉ%v-E9 7p?ǁUȶVNo v͟65=V+~/qO+^LrSʚ{4渘.%8% `##ZūIU1T'!%89ɷix(paƜñYŸX]|qU{TJUiָmA< I|5N3MNc^%Z`.zs3b)io֫hJ`^GB./ShR҇;kQJ#xeV/((nt>[HGNͺ`7 =u)\צY/IֿFD>_pĵ+6R5 {-MHAdR;o%D d$/%u&C##0HJyqNͩ0kdqnGq]C}} EFʫ DW-Eh"#lj^FC>Op;`ÚMH#~ z v9%d$qMMy` [d|3hj쉷 hc U2WiPfx^zy4 ^grh|}4P1HN-$ U8t/mTNt^) Z: YXh!p\ D)Jza Cwك[s.aKCz^FWݥ$ўv㨷Eͷy Īr$$Bpr kO`y4QPVHLI^B`࿤?*H@_|-(+O(lq/8݈o endstream endobj 110 0 obj <> stream xݝoTEZĘh#"J.QIp%A@K\*).iB,;3-;uvv}?og^4weEu޾Y[mܢ >O/{ݯpP_SJ_q&KFJ]ۙuZz3%_lD*c6c0]YL*xD@qJ{")lM2K웄und3TD+1ɩ6|g ܯj!m0$wMrPhdrDI2Y \BNb7KxVy ad;iy93}@m-|,jC3&i|hPy47͢GK$mB Yzshe \GocG,U ܣ2_**֯&T4zrNTV<{`an;#) |0zty, jɤ⨂[RI)媂AYqȡ !hy^aV][^3e GRsu˄ {ϙmⶱQ6Vi kcP?祢RIh W !2*cP!&UzuFiHz$`gS5IT R4t]B$rY- T2a㻔CL4arX84)~#qT^~xgsu`VCW%_b!MQI:,kLx:*km]~.5[u-b]r Be1*u-(1?n[y4uB: ;hÜ'hBFGT $Q*t%꟠7b-.U*b(".3biݬCOeJPbx0z:CKh5FpI"@hPۨEe ƮXAC)%Hs9: :Ѧa(iWHSj>H X,AOX^AbY@Hѻh(B/Xw.I#ěU,% ,'IJ&$0gl;QvuQ#Kknc=yB/* ךL.21ھL9YR1Lqu8T:zl]:z|)E4kJPҬɴ6W8f' %IKd_-Yv(pXsY,E(\rh0Gs$EIS>o82R) tZ~d}vDOXq*9Noֱe_IłW21; a(M7@>2U*TgZ\fj * e32J7@j%wu8=UqUqU2j8H(켑 @VnRRjZRq"W}S0 dlfp2el)8=O23V&óa=k=$|VgBp9&L{ e ^_ǚ1Θ:/whBtAY&k?:}<0QՔ396%V7|<=urN:xyI&:T6f&9:]ྉƀ2LTlL42Pù.2z;r 15<'lkMX[4>-Mػae/lhn4f`BA} GSyr]WU*JU*O:Nzc֊57n{J k-Uݩoi@5 endstream endobj 111 0 obj <> stream x][OyNB@ֶڪ=T21)8+(cEo^U=!{kxW[_7$ p%YdmbX Ơ(!X` #=P͜‰X5?X?Qt;A!+kF#m hMƠ-x;* 2BvMo/OWJ$k;Ze\_,O#- 2oG1ơ!$|S?f^eO)n^t`X+2 &i7IY)[-EϷh,L=76K/Dsl#Htf~>FP%\]}V/T5va}M5יzp/_bw v) )q F+lxbd>퍜HX'2+h`C!Œ˱ kTZjp=K`d>kr1t̆y5WQlE)`^mrwX>=+Nh JNXDvv"i s$Ca 8<6ZE!ugB+E+B҈5jPʷ72~m{omơ_GʋA9ͺ1̨1NGwl~pǗ10ǗF,Q)BHk8{ee LD|eC5I8^BE 1Ә`g7J~Wa[|3 L>ףI^:?OuTwoT'aZֲR,50bֺZT JB2PsQmf逥wDx o3ّbaC(L0 'd`␎gs߹;Ǽ{]VgL,B-[Li1T0JH86J7S;'_\FWrnǀPul>:]VZ.xȥf3g-7eDLVGoDph6uLޑ;5yP}ؼ?8 웗c ;V+|p Nem[ssL?t$p74k@ {]Vn#vxU{L깉3H2 ;ܑ[Wm?:F K?Chh>o)imkO4D} }ſHOs6s3?l5#ɣvZp-)ïϷ1fqK{cs?j^yқ䣘[|#sP(ƛ#m~p$c<ɽwv[sPٹTL\'wlϭ~f_M2Z.bTK&g$⒅1^4g,+M;&jF e+S㴎:d:{a2"l+/)bНH:<0&1/Sf Pt/m˹gدqUZs}|?4OK]^+`/5-E=p׌줎`JB_3 nK"B(92)?Cs8 ]|J1~,JőxПYoMV8]ͻa 1F+p l-^6VnfC񱵆$**/M~jLl*bș}F+'yU'gb+ zWjȧYEWΪ7ԝrRjNk4tݙՈamp?7D e`9|TF帕}Δh({&|MsЩ+P*OVEE2ŀJ(!4pG{FKib­/+Pvʞi=`[ta1?_9 7K-f̤l\'7r>{>1/gy"a.c&Mz7;肯ϙ(|%1ZYr;Q f`Y΁I7kt17P;y|q=||0K8Jv96J|I2H+ 8*P`9 nUgJbLTlpjcA7t(<gi3N wSA6nI`[,vBdz; c gN&}t*xiЕssux|PTٹ+P~gOUKY~m[o`_3C)0+kh@ ϋ9?rAB}ж,eurw,P}^=-klmW:8jY=$kӢ2)4ƒRFr5(f8>ט5ɘ U= .}]{QCV|rsOsq _A&.n>럐^J:x[%']'gMQ`B~pfɾ"}92%SN9@Ynm%7)_̓'0x6/˕gܣrl`߲,_7rnJf%cy +ʯ;88*6C2ra"΢8>Kݝd Yw+逻Elu`)$$kP#q(Fe=;Dob;ohe_'O-ZZvGZnY\HIMn7I897$]swe48YLL|Tc/-N;WRf61:dՀ `їwJ/n^k_V܂r){C+$7N+:p\weJ'b/.1Yқ37[U?P`.&&\_yٴvSfGDK2WIp৤PIκmMЩPo|6 UQWV'6&xE\I}Nnrs9ŊjuTsv%v@G V1Ot?ңӫө6k32 {x {b"יK| F񁫞Qa1 \&h^F? .+T}- >W6+SHT`/?8Cf|T_<pTKU?tO&BB!>EŶH+/jgWF45g>;t0U.OC%jI_!N3>ol0o3a0ṼZw1iƢ:(?gml&mpP[Xc3Q{D>fJ2AsXؘg lR֖^p47ڂ-B,y2n㳫A YϿ\K4>PL>2? eD!˳JXBԵϯxb ]2Zѿ)va'.C=RK ,aSr1XWz:շԗi.FÃS`F1XrI>(\R G!:[bws /:dukħ 洵!̉;i)ƶ*)`e.mm%[X-K ͥ埼U(xVʿJ\xk:F~qQt@)ֺkwKmen'2B+:Rמ?0Ϲ݊~WRgDR[$4'&t&3jQ=M^8%逫u{-EjVTkM( [,ԆZ)mK )jC݋U șsQ_5A7hƝuYV Ho:-VBVju< "h5N:S vnMZ$v1\sXj 3ZF)YtU;nn ၗ &1Sfel3 '8 u fg̦䋟eC,/KEOή:@N^V`,L.˜Ϳ些|t3Y( 8#tlWN3xrMl1WK]tg b0:0!X ?fF@+nsCI2#_Ȑ)aΪ7X&,V}3Cj~h.h! "a]Af>Bp/|x Db1Wa<zϗ?沎gūL#!s4#;`u$kbOt- gOndm\1&=j1}:el`h[nQhyuY3S=8~ά4n}6;g?Ygd`5xVn;/@9p|fMwϔGw&ʗ>ŝ궁ِqe_)]:8.|tiН3>!N;-kjS}ĊVCH.|>cJZ2OH nW77Jѐ?<<I:-Ώ RG*Uw7m j]xJO2I^s%~~,ad;"N+Q>zJZn2i\?pD,y3ʏT,]3UZYߴJUk_ d\ӟe Uj ,K96{V@ݩ[WdfA㳫/Ӂ**=1/:v}i-ΪXoRQF֯H?_MJ Y ]w{kV(*"IG}%-T1V$ȝ]T>O$|BU(қ%.&Cu*,ncHZO򏄸§@(3˱N w(\\V{F )9&\\J//;-\g!|M <‚X[[iqr2YJR"'>O n^~LiLn5TX^aooJFҮ$S%&:76WJhr&JP*{ꟻmLx%m]"Ҽ\tK1q,<`#^f"{'LG"{/`b&7,2V?xP@eOecb_]6Y;.WNHXǗ]xm}Nhȡ=\9MP_ uXCț\M0n]c`mmmdX=DOϕN_ZəJ޲) abI0ZϝrU0Xw |V2əh3_vYHCO%)| j lNǾI-H-_LS;ʹ?VO*ަǞѾ ,lP|QnLVCZP!F@l6K@{>Lfp'Cs5y~DV Q|Q bbA~=ʫ4t7OԶ{R-z|434R6em敢ZVco?.q}$.\=8Dw g&z3{ ߏ {GdwMʻQP^VFL=EcT hnb"KYc' %>L= W͋Y^xiwjV^-.Q4w UHr(ɜ[⫧naLCbzfqc\[e= êZfYʪMtUh]waoJ !_gJ95+6*şFp&Bmu'k) 6J6.JI"܄m(4NT}3=hLtW&E'#""1^ȩ!vZ剞Mm`PUHHxLs VwvNJxI~j|' ێ$fTҗF+H> l_ct5Op2{E?_A)N0ZceP[hB1=fN4oHMFP1ld` u411n'ɠT\G(3!VzB;uU3Z7=uD]6:vWCP*"8`\a|޺{Btrk4Ӏ5wںv;.of'RTU&R~DC4<o|c U jVbng[Sdw$-A{JʶzmTWF+{ Mn9?BIۻn+?T33[c(58..οLel=mj dOF3uyyBט 웗fwNގ #&]VTf)&C*( 4XGw]Z2q`Ngs%v{ om|(O-fE K}tɻ[F ёplnn ;'ҋl_c)GGhn}w[d4{d$`ybK(Px c#b *~ΎxhLTC=D 5F_:}GCK!WbhZ"PFeO-B Ml\bZ'+eh&Ŭ̳AMpe@ mGχt EQݶ pKkFU:-n7Pu$6DS#a, CIVf>n53?aʜ7Q?-fk\.Vb>p$}4} %0`,2 ZmZwWn}8&4FI#zg__}H |H.T@ Lًvi"Rp|}QikZͽTưJ&iyCLoh`X 2f"LT2: VM̌v7rS^XIXSuBnmT?TP8zi6+BϙnS8q'e鶱7M5ф󕞱Vh`n޺ٗ5 p}SS^Z-3( Xld 7|f0dMQTiKy.PthKRU4  8`b*zY &jRQGbv 0D 3\eNmPiha^Ɇ VezKp'`0i'+--V<%a.BihfB ;F]v^b VwPMZٸ Nt6he`^ċ Yr:x\YΡ]EG4xc5fM5HX5jv[{^m%q-PyPe(^(M=n$fl4lKJo"'Y 1QdIm. YWNӘXǯ1WL=Faڶ8}a8Rq8r--|ձ("󮨪J6; ӎz3ZIѫf]P‹::F"-v8bd6jiq]@IЎZՒT:!`&@EDuW2Zy}~ӎ/ɡ5sO(VR/#\ŶzhJ tD+j4DuNp~5::OFj9zKҫhk1><Ohmk65WXMzBMf -@8Bspg>gjWz )?W,:S:6j1%Y-h0ZAVه3Iifi}1]*̥c7FpDK4-TWS5m8Io = ( &5xŁXG-PaLa5|IT5XM!nL0-܁c6+wlZ(ѓЇ׌*UM%c`Ig_ݟ   fNKwp*ע [|U6}N7KՃ€+vzbfqa^OśxH\m1(NÄ5F`0 ڞKṆ19a$70n s$DEp-A#x7?V endstream endobj 112 0 obj <> stream xݝoU /"bTXZ Ո!ޕ{D%QM$PZ\D).Bi )Μ)Lmw\9g~~ܾsf;OC$G0+ekMq']O񒃷TYcꃂ:h\qSѲS2T#dTAB'v1V\Uh$ 5_ɠy3/=Xh̹:03ɞzD R~҉*u Q&1n z@"ёtL * ℧b6:^b@,T3[ 4 ])$螉xv7&K+51ycZ)춉J2]V䅉t#MP+ch{ Ncn-֤fM *]$n_r 6&>$kn+FAIYKJL5BPRSD#'2Ml6:ݤe11鬒uӑs(3*<^KC>jwOAR THem츰2'#mZ]UXX>2AC-h{XPɼ`k/Y؜meMUf1:5fTxhHRiwR ѫ̷4 h \`җg;?Yc[Өsa8Z&n\%҂VTr80 .;=9V%Gd[JA܌aqЛ\qugR%bٿv`vd2f84@%pvX6p-*7n'wN*9@o4wvLv/mݔ߄-٥XN^. uI'E:.R)A%[3oqb'5S7t<0V]fpb]~s*dpU3F|vaXv$ .+>h5\wJ;\iPdOֈ4Lo1}/,_Xs9M; 2жa(%̔7 c`PKnӎIa`L c S|y N]K;rE;r9~9>xIc?./[,T^2Q?)4&iv\I;r+9v9SbjJ}T"&7HQ v '`O2a >9ߗ{k.K}1DJ4B_t~@svfG0U}/|0gPlaBݵA/}#q}wRnWڱ8`wIS8O`_훜nWrdDᅅ.I*sRy>/Tw{]$q tX [8*_n0-8c.H2- aS@4 lÛS@7z5 p%#iEQKyunliT >r/c#82 Lʄ dVsP,֘{U)g7 61221}yIhA˞Oh G͸ g4Ē @12U2ZA[V,vz2*3蠽22fǞ8:yXm9C2>ik :o l&F3sb="*y)oGTz\fTh>d68[0Q<5Wj6[qB"5St㵦|o;&qTSd6y7l:F,>`ҡ H\42ؒ}aE>jPk.Ӌv:x;Wy($>:^j\V=2 endstream endobj 113 0 obj <> stream x]sF͟31m\eo;"{]u{dmU6ugٖE&o/^Kw@J>(~$JrhLO"(6T MpZ綠9rᅦLVri/*Gc0Sn]Žo9r)K*+0f컞Basr)LsWQՎRBam'9r$6S> 9}Ӗ%|ioާ9wfS` nE0X>nFQh9fmb<2tߟ;ǻ|nXs9 f]n%W ^%[`'콆20`.# m/(7_A !`ew!* $#S &Uĸv8GvD+F`u{J`}^q01=.M6Gya0^!`eXx5Zhz*a4 $Z =zl#;nrs'Njy'G㧃C2(>v-Ba`JekpO1q 7bV Ygʜs1Z2dP( ~ R}')o:SÝhb\36E#ʣ񁍇 B|DZ):L^S< z~͑c*[ 4u_sؤ+{,yN$F7QQ^Dkۅ>)!r,Aм٬%BE]^q-&ږGesC6$pl3S[UKb< vdSrgnh4qz^_w-ʈ bMGFh5=W#"U[4sNwFK%ɓ$1z.5|WNX:8_ .uhÙ^t#S*.BO1)ǞPW|eQ{_rQR~'OJ"24? *!1z=9.F]o[vڦpn ?PljR^ǒ Za1/E-YRWs`s" )_𔌺hP[Bj$as7#?;%|Ȏt|x׵as@q!4!!'/W7T~aw\ ?ݰ܀ }䮦T5#¶2jL|mQAI@;'׃o)}6Gb֤̄aj&ŇJG^ax 3|ʅl Qo>zS y혛A7ىa9Z4RZnn\_3LThǏ 3 Z/D[]K\;@@(U\*CA{KV<C0q9pO1.9@ HAw$lQ4V8a2N81y>Jv51y/y3a.1vC|#k*G LbXGh 37 ƃ> UawR`Ctm^"23XLT,/GpmoTHYCqygD#m,z'U!%5_#ӳcQ;=OB.[O&+Jp#0`I^`5!-)FXmrT7>EF+uJ90J,7jWSFWͫrp&YjJ{xWJc{ybL<|0Jl'f"R ʹ~Twrǃ'>%-",b`yPoO~3{5 ݚ6衝*?mʮn0m'"Q_,hm2'NaĖ!.>-"*'"g?|;鹡O̤r|u^Aa[mNuvL05(ֈP D5<+ziJЌ8ͻA$ȓzGn?^?wL+촿Oo֥kPh;pPu)s,W}n\ \tCTjv䔱' @zZu# f.\f?fPWk5 .54X<ؘc%鱑_W6Q|eۚ`0x瓥␗Mk#$@㙮e\@:aTjjq$K "JUA3ZMbԏJcKlzn~i H].MeB\"d;߄*Ep92c e! 4~5XUJF+}zXլ _gڍ6V^#ijI7dJPZmĮ*UR ;E Ou{uzPj@!F:{J@AfҪ{Pssg?(I&uƃp;+ 6u S! zLWC#( rr3{|V߼pGOU¼(bM->u-;mP;ܔD^⿉7=e#g`_JB!hi kV\4JܭJ2X"BK):ߙBNO'O:$cQT*$V8ԏq3,gm b)ognFknEb(TVs-H¶*ϏF+65PpznhÁGvD $[vJ{`C;M})4YoC^hEVa`>r!Z\i͐y9UC}6w9 ,mjYi,rfح@ J4S Y]]E>VUCJ%'[íAh0xRg\S%pF-LJl1[b&]ӶVΛNg|4d{N@NWF#rKVII 7v0Y:Dvӱъ {+LcU ڻ qr^5^&,GkVi#K*MB?'Bi*L7=[.Abv[o<2CǼ=SX#%$=-Cݵd(X{Yn`a)h)eYF@z*}V`dG[’nĪ\4lbmwn֕Ii}_'nnLY|❺b'!LhE*cZ֔98p[*oJenHe׏6deUqI 74[м(_?:Ciu Ez&L$y7:)gDH`"h ĈXMP0T1{se TZb6zI<Jsn/G"XHf{^gf#t Xl_ɲ oGfuOؐg)h@Άqeu<}{(jDwwd7ڤbȖs~ðWzǝ 0 ^cl?oPWx]Sozr`Dx' I)_lu8o Np-S@bZxlRo!?{K([h:IL:[X'bo¶]j =zoy( U6sQ Y|HQeR쏁=W @-$_RB;J#pwЊ]VzD]=xNoj~=9lOI @E>ۖ\6"4P hُB?Dν -ذfڛ @0a]xm\_V_&r'Eܺ3Lߍ`S(u4O(r -ϗ GD $M\nD]%LۡX]{mQMPyKs]$:D:"+X,-S6B(1Q6=5r*Cf' EB:<4KR#Y 3Aƒъ~rD!0:R3C;XQOLu^ymЈ@ʈfHF7:6 WL!A`*;]k߭o2Պ9/ /`{=y :4)3Z2:Tc+ $<{*t{髟xM*Nw%)%Lrh5Q> Zyr@^1c|}xKyD_۶<Ň\"D%.]U$T:ZJ͗?hR2`</irF'}N^@bIڕ*msP @b;,7LNc4Ìl g,I P!|aRq`%&sn$:"t]0T0Gt"j0'ảPQ.@f ZmB3}0D]d߮XkË T|Whi|\%nnW.rX\ pznZ͎z&l. @_v ]jV]3XOoT&^Qjz޶xEr22Gc*ѩ̦6jhƅa$Bֱj'5ML!lx\MӧĽkzpζv=oF!YHc/ 4?0߲.-N3b_q•ź?h9 78P]GǶ?q7J= g"S97Rٌ7O7Ǝ ;#ϑԺd F>t?h߬0SSSݻpKf"COb|hk#K-u ILҙDMg[Y;)v>(ܾ3> QY!y, @ y{1Q FkUa~le^j`NȜ'UWOcb\q8OV]5U=Pox %8;ty@aqj:/Thc]-s̒ƯN[WT ;$>P1 \r#FEk2"d˰LS>K%v| E;(a~+ RW<&3$P8. "9)}i|Y"[ZXE RbPb )Oou^C^KM{^yGv JJeECkv.r*yp?{A̚ -'|kzSVޟrٷTD tMZ"aڽTAњl[ |-){Z)v . h/ B^8GɣAu*>9+:S ۮW-Z\ʉN\%\T@(ZR*}ٕr0Ifbmz MϟhֆeF'[xMH5>,gw04_&rb>K`.]|5[q'+.T!@r}1zn'n,bK)~F<8uBv́9gWHsv|dmc-5Gne'#爢dQRL+s܍X TFhaeǃO9h5ˋkDSa`g|;tpG£I0-0Ӿt;5?|&0Jyh- ix8"0̯$#pdovJN}Ԅ۱]?&5ju(˰CuŖF#q^U Tan,[ϽôKr%ߟ#n=YQz7R v~8Uq=wԤ¦jhZ/ h[䣱,[Ś0@Y7X0np2JSNP1H#;kJHũvfdy*@o9Mr[C$<s}6ûNj7fVnvanӖkf=Z -fdo[E Vut(? AB"S eٮFعgը}.!ĀhiUfBž=Cya; -ŰUː )hy=~yN]}J#ff Uh+Eq{ BNa`$jh&M4Gn8keъMrRߌS\8@cLb'V[)]Lh:~v89Z&bψ׼QGts(+[&"T~y;XC2a2K.D_cԟ,z.s)O>G9g褄3cLdnM$B)"9\p(5DsHgY եe`洛/~ׂ|dxiDsmOpن O,#9| "Üdc菀?#e'+xFx֜Ԍ \ή吧 e+|> s?ry* XB2ɣ)e$m'ly:e OuiS+.כ0>216䬇+C[&LD&ىh|)ÕkaǪ`t([|( VcK$hu5,r)h|,t7exztLA|3P=x,n X 䛿f&C(Dt>)_>>a{ћ?łҭU }]|ٴ: ,ȁȷb6XV*ih"&,_*R@ZFF~ Kww%FwdI+\,:0`uWLц,ʼnJ =Yw] X8̓t}ޘ=NiTut`z{N_ ҁk=KgK,b_&@*N([v_jqmd^bGDtՖgƂI7|SrIt\!dFeP;ᨎDkQFLwi-|dZ蒙aX (G+p-)T $J55j ׾ IUֈVӡCx$yK`i/73"وih[vR33[(^@N"z>&8hԢ+dWc5j=^27&7sX OFs(H9@5`v&vv.n(W :]owoVQe1!\LE`&a7>xF⃸\rMkjͫ{.f\X2?{">Z$\%\CU"`Mik .ZyaMs\+CypdGa?0d&#+.;,.:"Du#k|iWZJr=liq`54&5q'dXbF/Vx*NNȚo1e\2P%SQ rHL(ӛ,@єc E L!d<+ڗ 4JesVp+ 3P-bcoB~ jc .c`ƯެƐ>D yR!]uzn'ֱ =n4-$dn@lYZj/YO}Ȋo,W9$8h<[ٱق@#nȒQB#MqKȔ m{ƓMmHF#4Ma}Tt)'3RQ@C/mY@PǪn)homZ UQu$\_&UQPDKNyg6a< -e4BYyes}J%ɊQC+O;!-C; L-0 @6}*Pm', yvr!{N p4- ;:c"X _UsG OW>U'pn]bĉ 1 QSB[D QVE! 8; 2$Qs [ֈHHKcӄxxx% łsn-d#dtCb%`Sv)5yv\UB6.%y$NJ8/6Y6Z~yLRmX5%,`}g!T%0v9xV&ܚ}0{اkcy{rX(DuXq},y7dz#ǂew]I)=*UO<(n ȑAA@yzsHVSskCfBY5Gc?qhĈ(CL) #G)`vuzHUA'gmrH}FaT*dnDNHߧ>G5E3"+> stream xy\TU eFK.ͥ(-73-M42\-5\33{1MS"MCLAEA]`Yy?w;wrνwGw}ιϜ;sj\Rθ4˙7~v*9Qv*yngi79#}vڰIxB܅!v,BRx3Dۃz 񱱴?Bߘ^ fir{u/^9Z' h)B#--ۆN,YW*+weߦ)si=;Z)`Fۮ }Jck!i/4n>ǯGւ/2ztinG{%vT%+aφmY&C'4KAֆmk9=Lme&o$}efZ3ƸP"sf.9Yׇyʿ^drxx*~+\6,aܦ%x:.U} \0MP\z$6fNCXQ~w-n|QsuD]1"NJX˰@CzV5@yUcfʏt ˋ=i[he" >6vNAt8ruV=X!(3,~ Ri2pZNWP󳐵k>hXDS/zVGTc6Qݿ~Wo afR Dj#$2k}(p+}Qԙi=*va>4J zI *;ͩar=5(-"?Cԇ"j^EAi&]|%˄S5Pi행uwWiB+T%aﳳ>xzO~гr2stK&#h%BPFOifd#!\H] *qs} ݸW|%y5}#BSܻ>mF&ڨcX4O*-ƏGv>ohN)3ZHie d)duf7ߧNQcv)%H+q2~JjXK]4T~_sK" H0̖LX[j(?Fk@ߥ4J e,d,]l9 02ܛHy P #Ǹ߶>uYE)1M蘞Efu;:rLihJ`ѾEux'#ߦcj0-- v}4"5cRe#s/Ėah[/7SqK4,wAVIIUe&.B`;.'{r 핉&'nG׼bj5y=<. 2 bsÈyv\gHܝQ &$Kt#O%KA[k_  B(QoIص.fJɉZmܓL@DQ߲ ٧HSDH0^q8 DTGL(\7ig/.wpLp?{߅PɮEJ7A=OeI$OeѮoM7vr~O=h|l͓jN&%!=k^?(GBI,/YDYȷ8}a~ulf0iõIIr,=46l>#*'a/xKr6>(r kL]4&lywJeO3_\LP)]IvKVF TrpA\2-8ZkB@M/{DhBOH0l^XZNAUlN9j_"YP%W2: ?X )ITr p;,ȷKEz6r &D0Z0> stream x}W"t@3 "9a4A"{ gG%^{ݵz'50Jq p zב8, _Q4@)'8=!$Q?q?lPګ䑯;2IJ*T4⨉"$ ѧ'f 谋GCٸuĹ~:}1MBv@~7ݮIƙ}5E-&NFfk9  $Aۨ d+ިP!3'iY Г> X`xz4 gcC כ]L)Ko3KɏcPPC̜'Y:Fh5Jg*T##`>;ֹ*hpK̺.dp Q^3FqI m Hn$h ؔrK}%H;g%AE@^4S@K~_U+&#9a۝*30n(pVيn妐߾b{t! ,kwj(NOz\XoN:x(`+Mz.MFP R Q,B>,[u9;Rnl^ )@g]xZP>P>îˊ\eoDsȨ3|46WQQ@Z( _s:`GO\t Jx!)j$ 0XB!&xtBڻz?*6;F yB@3s#U~Wn>©5gwP a$R(^GtC0w{F8 {Du1'|T$"C$:4lvԠ{3W v4 (TTQKR\!<,So&!T] Ju#6N Bsj BE ^kg?R0n8佩z9nYb>R:\Xs}E kAAKq(Ⴢ$3ܔf7{u"H1` r}SpҪZ5@I.v԰;d?"_k8I{(U΁p1Ƕ^C@:ȯq~ "EPA Ea )kib4~2q!d7%BJ-1~$dj;@iPӞu|>?4φ1olZ)d qy<>Hc[bS2Zad j{dCŠG}^GxQCJ c|N$cRAqj쑸:F0_P.W+V0薧Q+p13Խݽ뇝* P:'f '\63@GhC) 4L^P ؙ/Cૉ9md 6Yzt=l\䑂=n39r.c:ZxM:Na'a}5|3 "+o;Rαz甌 njlBP.%XX'3(dfV߯j |~w~On eog}pΖx?Q_žOrh PU5k e8bU\z]ſ\Lj;N/6\@aH 4u gv [#-ENt: Of)|AW:UzYxY]%V 9we,PFnj0EF !/phԱX1ޭs/G2-@bfj yz)Y'<}SCӿ䭢s{%(/JK!XĶSh:%6l3çoKVP59Z(#k])j#X B{y?_ 쟉4L&*g)(-ڻzgKo#+:m v \0 "&5RI4xjxhƓ|Vٗ&u+-F ^u[P  V|I >> g5CҶ?)f )dUb nP5؈ u,5]xtag=lιko~F fAc:\?^ɈqRК׆*j8Oz8AhgX:.2F`:gmvs@X<8 %on ;diz1 #Ytc ;ckBK# :Y^#A'f£;;Y9ӹtva&U%\4ᤪJ(d5=ZQAp9Wt=U(gvXd7կA.`vHu: .q)dq/DWz P6kH9eTR,' R\ Q8Cu,frqWި{qX!J 8WвDv7~ECo} [(^GVK#zRes =JY/gqE)^CxJ(6k"{K~1n{~ Br <#l Ӌ)7u~ ~ fcSGӻNqzW%\qA6f|0^nnM]u }&w*ƮQh{8PJE>R, ^8v/5<0h \ϗΞ"LjYJ @<-\\cQ3Ntn1ZxDž~i&̾y6<~;p2T3 z33JPvw?Y@̆+'u#[B8Bl!!g4k5{j*}359G睎'c|`?,&jL;`$iǗ[.CfbCZVz zxߑBAFtͰ*T^Bx{H/J ɍy6Vc-#'7OpfL3ZZW К-@(7s()AO*ZP `4G.$*Z*ɝwNgXZ>߾xPYJؗlEن:3@H5/jgc)>M!k]Iڄϣ7\.?hO>[_ƃ/$Ǯ>sɲ׉,Vq6sI]X%u(Dub[:7Ѡe1(.{[m_yx~%OoqVьA*+YEkP5tVONhnO4XeG} Ş e>7x8JylHieT.zo lڝ'SV;O yeLk'#Bu⮈&07} NL.1:CIw&5ʔ4 jՓ/が?tp3 gZ,7r2-G2JE-aU:0CIU\8n=-0lo[>yI Z68{?0*(t%uġXqƇOL =R.`Fɶ~]$1qݿ3/ZI޴Xy?٘H4C<ү@:8TTH^"6ӞB>y0>c ^pvAv/Ej @Y' z3gDq|aҹϵڄh kJ4p]~ *,Mנ߲NޛVP8sadxyE+ _W)SRoʂÝ"f2RAT9)BQhf{8~XMϮ2L _l,?xtck/ʇޟt!YۮςSVArg!w9DԶe@ 41=h 8:ďAr33!_u(PڋF{ Zt%LPw%6 :ݐu"L-&=ON.^+k,x=AS/DUlkG!$󳞄Q~ -lZ-M-d,湸*BO@:'oHP$M-i6 Z8Qx? 3\@)Pq! ؜Oň\+,>!OseiSbVēeN*f4Zm9Q_F,˵"(luGx1'Kk=ǹѹ*ybx]wi@ͅ84#G*l5it$,&^ڝ^U8@V߆eбVߖk븂i; Ÿ$K̽t#*MTJ`*R|U N^ل'G,nsJ˃>yDϰȤҫ{8/(9H?CHuue65e $'oZmBqFZH,?:RFq4/_wT+)mRp4@Ih7m?{8š$>D_?>- 5y[R1706("KCx#qrwߧ$}SSM6k^k~?ѧ7#$W%\ÿdqK̚f>,_[x}3y(lQz3\! @m>ky3"[p-aFNAEK>}Tx{^)O `uP]w~'CŽH5Òd!,>[:q8Vbq+Weoɍm KNʃeǀX%ߨ'"`)/.H+$Єto=,3@mjh3D]`~rMCJBor^t#qߧ"Uz)e"J hK6+nvw_ܯkTɁYJ /OlwY}bO-KU;vwTdS3Pgtf^W|dW[a7m&3 &|tb{gq?7,j;ī*E- R%i q@,Lՙfw\AMonG"YewGB:މ +j@{3ACtf_AHFh߯5w((5MO%CD(L]'NM{N )]wtz m-(HK)PltEr_%6Ro;|~Tw :% 3>m|k׿܂Oo>+XSO{j*3`۝^f?q>Dyii^KqMDz!XK)Pe!iLK;5ˤu d sEǀh]s=%ub!/GO+4< 4¾LqWQ@6 Jo۟F0(%$DzCnU_obUzŰ >־Ak #(ry@#TDלGTe]o_zܭy6lCˇ'>x%G.) n:4Z^GVlADהS!WB l/fPqAY:XP.Ć@vlOls8ߊi :/arAMj#Jv,^VE>wwꀙm5=*0?wȖ-FF8UH{?2~7-YN}=X(zU167.Qٹ,UQtw5GKՙe۾QZ):Ocݤ/xNބk'=$uBu@dPRɅ.? J{k( DĞBwՌ@PG:{W})>U B!YM!y"y,/x=sEAIRMg:dU0I \ e;)P ^%6>z>XU/؝T<?yϢI-j"iS@[\ٶ>Wo-NfHaV}[Wy`-y&_5{DLgRsE7~It2{r~j}*B&amYܑr($XJCC rSls@Zz|xAsȹJ\йCэpP~ez8odhbJz[vPZ=z?tEFBD +(<3AE4y}u&_SgIrX퉣'0V6 {jؑrߦ"&ary'n&;c(Vk͢%B7*,M> ց RvlxqCr( ŋ!\l[I;ْ'BD TzEfFżTdY5M?;eϰu2Zf‰tyHgr*WOAr"HlHqCUOO+,Hy:9G7ʶ4WEנx`?{<}g&]x)g_9i ֥hU:ZOE*>_YǗ\U(hB=Ohg?(wc6t Nr˾ {)d[B{XPA`׉濌&wŝFoADxl[̖٠(QM*=.\%oǼ>k)̱Q$6FF>_p dL1 t vxUl6q40؆Ϲk)b.nĈjjzi_#A~W&v BdƓg _xx$oEvxضr2\<35ci =Wt6iLoqw#ҦQ|!:j#:}][3B={Kϯ2~.g5}Ԅ]+gRRMCN*e)boJ/ڃPfK\]VnH2Jo&V~-F5W8tyU%+ݐ"^fwYL`M`ڴ)fn|?Y'Gҹpt5W(ٷ*zGzJ@i'3B ڈ[ĿxBA|-[U$8P+9֘@kև^it6@^u y2(ͣգ"@ ghrr&[rQi._'"͡J/0^L+ӵwnN/e2L$>=~S=iؾ+ @Bex拺WO>H[q.<:J}EQ r7'#}y6a_]C8:Q^)tH؇)uQs0U7 S((֥h>¬hvpoLԁՓ6pZw$&E\ܺԌ<^ozJ[eAhg:oA6tdo0*4xnoj͛I 53i&V6( k>mڮ0P| ?Q_֥#Au@]vX*]dsgW!ztpn'^dvjJEYh>qGzLW(-)z~jShx T{*z! +5f^7爺.na[EUy-šlbRLMzJ)>dGʿsJO# t;RP^FИ?YfsvaٗKxQCAfn7YuBOTc`K῜Pऌ*W</3V Ճ @4O׏] {?مB>SК9u<@2#8b%l gWO@_\ES,Bf5:«'|ZA}(͗VR7o{ns] J@T+&_r Vi'_~$G a jҚU=P &60=~`#noT531⻻ھUzexӐ1tH })JS*iex!iݽVe$`4Ŏ 5.ָk9ǧw&+)1Քfh>n=jXKL\|l¹\ľrK_^oV[˹qS搂B/}hmu>nzxfbנDXL^U~P:S}^G*A{zkbcEuUᒴs׼)'±o3M. Dc3QCH4׺{h.WPe7yU:;-'?H]ܾ+i]>13yQE uyD~lʘ4pHW:׸q~7CDMGX*(E.@-ͣ$ԼJ %0NXq𚜋w8(:BQ͠D/$Vd ~`9>i^HzZЪ~%u 4ۑr޻, K]>.()d8 4AůcJ/xQk) i''==y딹smh|k^ *ͬ3ЀO}{?1 _:0{3]{#rˇ)Yg U~@xt+ TT (U4<|PZ.*+6ʽHy Fj# 􇯢@D@59N°;΅/O{q43|aܭo$JgZ@dM,F!wC^Aƶ4r I w)g_9Ai m1N"zkqۭI8i;j۟,\t4Mc\UT)Cf0PM1kcәLP^ݧF/ʼNGU]Sh^GxEU9#ρFozlXN+'6o\:~$#@cZHx^2|Z@zAfU)*^ NnR-w\| r @'GoVu*䄖*=@CcTʝsz!&ipC35UJE}!}aS|3g rcX5@Hhed5jwW G,(S44޽:*&8z5]5)͏,J-aQ*3?Vp۟[ǶDZ"$0@+4PqZS3*p2nsZp(F)NGx$I3XUva4dYNkjf]M!{/={p=<X=!'"8m(X&(1}?*0!$W CL\f0xF- ӰS`] П98 Y3#$'YJy+nV!}PTh endstream endobj 116 0 obj <> stream x{tT'ل<$(E*@*Qz푗PMpB*mJyUR)$-&1(9 Bv7ξsIpｻ;7s `ߙ;7B{̼Us5{ >& FvtH8Ps ۠( [F2ԞWڣ}1 }sFMrz/q7gIy]1Ij}}gVl<0q{ܮfWgwDz(ԖHrxLηܲA32h:0c\ ѷLWZpB6G\aUԤ ]]dvlԋNӱqRb{6]!$>:VRK$|>q#+Own8t1fI 8g{>Mcep֩-~1ccaXw ~&m1۠㏖y ] #6 Cphf8AL֏'O=E*`3OI -v6mW m?'I!Ps5>)4 6[x+u\֩=wakoU!*!wzA .=; ZM;fp֎yJi}R7Biu`uBh?-$Ch#>?x 7C+j1=Рɽ'B5ЖJ*o< zI EHze$n3wz@AEmBB x"7<%uLZ!x->J;SKGzHԟI'QaܛADJVcɞ)3Ttq#ug)np61u :X$vj b&xnB \(&IZޘji*I 0sdB9w]ǻF*NXE;[KiXhHsEY`kU?] z2@jAf9#4tVמi"TF^!$WE֙;gPb)uZeE[5]f%XC}Q殖?hxVT,Ci8qݍHo@z jcQX8bDLX_쥽BrWhoތݓp ?)=N+ ۷߇Fm?cgI1BS۬-VĬRnIr&4֞X*Efxmu m8%^up ?֑cGY)BBeB QyR<BKauuqL]E<ѵ :hYC8A MBdB2I* B[Ly  q57SRvlἙ ] ( RsWĐ{8GӖ6x?,Aef.M׆m V1@ܙj m%uӝѐ|n_0h#jrT5w@P'a;7픿\>>x:.i|”|nkI{Dh QpO ~AthwjW*wc{Ԋ}y' Zicm8-eE-UcZ*Vca|9fDDz:Z8w^L&b3)4tpT'dZuW&ꖊ2&cQfR3KXalhǧ`r]}:3O({Zi*f\aϹeBGS犫(yO-{hF>uŴ/]r$xqD1tJO_;ԲLx s:# 68p0Ā|y߇.!׮?ux[fBJ,n endstream endobj 117 0 obj <> stream x]n9}K&`,؇Y o&bx2~B[݉NE]Hd{*Vk2ʨ8-%.F+I9ݯ?ݗkOU˿vW/_z~\us3߭6)kbZj{׽weu%_n5{~on?﫺^/θQJ^-N=uYɕ\QkcLQ^7_2hbKxhL&qZCꟍ9X4Fch{LurƄs;mKoҾ~L|@YUiV?o^{$@Y^ vG/r(%n+@)f ?1{ȻH0#`A {+ z9ԁ(=1ea@Qvv 8*=Q$(лT=ێQ:ph^ ہt^1| FGE1Gݰc>ZjZ95aXKqMDZ #="zhAj mqˑ]! =aixãYR`::y"X1 "!dY+^u-Mh)d)l&Y[̻߱ٗܧ^9d$0@COXu  WLnp&~O01[7MX " +l M춸CqS#"h^D!-@!NEGGt~'gP.!R^Ehr r3ϑX] \G:4" !3b}Dd7b+I }Fáb@!!\]}!|_5F }x)7sAxK"hDri4ѐIGar7K1TyV hoM܉4 a"^̡CE &6emk｟@5 c6K/=h6 aMtW'P&Bw"Ƥ_]>>}qnou~ EHPQvv,%tB} 2q,|җMkϖY]x|N&h\+k;͇5T2w!ty0@on5qCEɮHCߠ`!2#(Uqx'4۱K{?4nhuyW&41C%>6XINC>VWywÀ~zy&[] B;šG0 lȺW2A;Y8}-:|ʏ a)V}#J"ұIѻi\^[K:h=J3^nl:6?~aZ kp)$V6Da6g+&"SJxxTܲW#>F 3)z`w@5ʵl9b٧WT8}fjuΨ "*x+ixB#_o4vK%H~ׄߨ+~r5D7eGAdt߃CḐ,M(&nGQPdfL>'iKrƵa ju0q!(b iYWtEpW~,OREt&{}b4ʙןKuqyn?=}߫>8Y]~`5GC Lo#A@]Tv(}E#[k;+2Zk&B)rj9%Wן.9 #mj3jF{NGWJɨhN.4T(mM*fSJ=&^o*ue|)7&@}rV!a#l{|T[,jCr^`W *GuX6UE8Ŧ5sT.8MY)h|w+Ĭ}?Z endstream endobj 119 0 obj <> stream x흉Wߟyzd$B(q"7~`~3MPsϜ99 KU{i8XnVnB6^GK.r"bxȈ  (t2"g Ph 3bbѩ7K ;@ F-hزFnA6R| K͸ ԧ\ ՊmIۗѳIʿ=D '?0@@o,P^A7Ým]+G|O6뮉,~ 5;$8:n~lQM_?{J $i [DjJ#ɲlMn?Ɲ ,X@b>[ | G 'j`8`WYRuŹL?1BM v^pf:>j{|f/øJUhY]TԸ;BUx-Mn^tv {D UP::d`^XVڴW=Jw0+hVl.*Ks(=6'Mgkx8K/c9m=VD+dž-kxF (=O,u Ly>초^fs(jo#2ovM&'MbZA^Wg( 8 1 R҆X_Q{ fD)lSI٫\Z bkҫ,ȉ1)l/nUPlsz:^%5?nG- =XjⲎgl蜈^dȤY,>D FDOɿ;Oȹm[KB;W#kKGC!f~ټoпt4z2q]/ ]@a753 GZ@OHex'vf9H``vt:> /{B!YB u j&r‡[8bExE@0@qOfjPO\ڿt~b/Uk$ȐJ5uH]079gT_dpHgbQ()q޺4ܟ-lի^^Vv\\֔㞉LW3DR07oڃ%>>&6_ȶzձCΚ_8ͷ%"gwhq_7daK0ȉH+mQMY; hAmM9)S.R«T?XRkh-^&2 HwNci9sntL܅Ed?q[I5 }A8 FlE`hʤ9Ew0OGoqܳ*(w~WUPn `?85%s5|95)u81^'atcr;c-(9mhih`P7V͓m5aVWێԠ&J]9wn::iK|gIn !:HVGCHhO4+;Gu`V%'U(Eu)O/Qp'vٜ>hn#ϾR]*"D *<`4bV)ƫkl->n%/`x6opMY=y2"{xS~5[8 XA!ҾUl` Pū^wM{_b"zχ؊,6Ó" eWRgFkuͫ.3Ljq b\~{b7o'?9ETFoBpc6Z5H^ɓA(wA/F34Ywh5Wh5L2iVn{Gu,\\=hU-+ [4pXxh!7ۿxr,K2MXI@3<`2QtbEݽ+/cᶶpҀk"x< >pXm7DDkq6?*ִ͸3Hz'uf$')WB=dvQ5<nka?M4~`a^vom &o36's00o3v·ϞDv󇂫6OO=$qulDD>\V6'x=n P@Npl#rcqdunoDdx8zVGF;GRgI (t8Lh!Y| 'RVHzuj\R&ZbWѮA9i8|8,mdT$JX4$]BCa}W<U]T+& H`f?!ç5AX>~!={Vh ?UD`ek0)Ir{ fS9Dfڻbhit3Ppr6bcQ;$lۗ`PD? Jnpp̈́e2@grɀ6|-n'LӝfMxݾOQMEΜiDzFq ;؛م2-9-)Eo>X5Q6^i~cSQnJ'ɉsi`ˣf4ڑ+X!NDڢsB9iS?n]n n 4( 2ci^HY1HatbT̖" )QXX'Rk0ˉEPS{GؒRlONOP .XYV;U|Y̶ [| 5(wSg*Ujz_y~*gOힵN3HR- rs]uD"IW9 >Q07# r"26nK,wψbgp ncK0hZPl׶(;ɏ=vY[WYV6Wb%)'龰0y6%m_7/>n;.Tsú69~"`#u,S%.ʶ^ϭCQ.!e_I$q6ٟ/\98~:N,'"]%SMW EZJc,ni-^5 1Ws緰Tpoĝ<_|9 x.{o~85+k` m}r:3c^[A{O7к_dZMYZ_cg"Mm%4(=j?͋=cX^ocMD EǍ~W?P V­Ejq9|Jv'z~fh}Lɒ"T+9 3y}mvHؽ0lx+t# ƅl. 3|bGx0FN`:-^4rm~zaX7qiDEsTغV/Tq&3gO {-^;_^s$˝~9ؚBIRI|jDFɘFGۿ>Zg. S-%`-NlBŗ0POm]+к ۇW5X XßX:Zl'A$Y#ӇQ_3rԧf ImF|J岒9m\0z~ۤ06ߖFULgz< vjX>~1i U:XkφS}G+.Ÿ#|g㌯vLeAO&7 MOaT)'v/f7 3v/~.q[\95,>6wZ)#o6ַk前s!>?}pzq^,ǎ^8>N3ѳHw?灕cVrmPHg?N:KCɚעZyf2| f`WeEW 3[=,|)y*߄>>﹦΀Ɖū>I?]޷p dDp%gw$Eu0z>>[<Bީ=޻ w9ԞkjO=-B;W-;dH B ܩ GCoq~mJكjXh fLg9x_3ֵ`>8G$WPpeOngWlU-uRAQ4M߅imՍ-V_Ţ/H>[ܲ|lb㜓FIb!#<w&iSw+Vl N & jaa',Gu؃jr4I*"W(7wUBth#!=Mh%G϶U$玹aBiW.rexN-b?V"JsNۻ s>hw]H2rou([d@ P2'܇Eoᐫ t]=$v(-[ŔvKG5;ڹމtu ?dt.ݴ` 52HCl5QrOXGQH h`uŭs^Mx?KMѢX>Kgu@nk Ţ7=)4XqwpBi L?3B {N~C*Dhӯ9'+Ƚi{KՅBx01"|9ظlAg RzLS7$[wo7pELKكR}u,DՓ@]@ ;ȓ2(7\ V7:\%@j`5bZٛ9V ـbQt@o.Dhq @ e5/hj49}!TeNbcD D^%CNUf=7=Ag$gGZIq qN"Cm?J{ vNӱ+6C5=S{#'#(MlK|`&w i8p9zw%(TK픰+3ۗ):9Cqe,TwbMI#&͆{ ЊV%Uv_H5/"gSEoV?"2G([ѳ.ɿ_FZj8j-dXw< dpRgXPx U.4I<Cv U r1Vk(Wmۗ]BIKE2˸ۛu57<^[`}>mz endstream endobj 120 0 obj <> stream xݝoTEl˩F"X#AAPr(mIDAQ9D"Qj"PT Z)---{~cn}g3~?܄Ar SE߮[̰M8t=rYܻtBoDӻq{x6r{+ǵǜQ+ 1f\Ǵhx%wJB>'osn4;ÝZQ2x6(fءfZȲ(v<ܼЁ\&@wl \Spo4z&vivScO:%y ܾX%W)'KH% cMS1D0-r6ܤKWYދZh38IY\ß UF(G m"@`,:ǭN9Hl AY{kzӦK2?Kنu|Ы(RRO_ ,eܻ, 0:ie<}. 0a٢RP)` bp>褻+,-,cl+W:2nbUJdm,ʮ!7$"v|[ &e &SL|Ȍ ;8 0)_cGL~P06b.2 6#$v$% a`2_[S1s1&fu'gugI ;g1}>UYu9c섍- i i[|N]rNi>7y)^e9J2J>H+HrBÎ7M\x@vBQ~]AY{ w;Q osyKN) |WyRNTM$lV^7z+{ Q1*{w{~RUWp}x☚MŸQJx%@9bS1n+Eɧl\oCzBڅ~*cRǪx\ހlfIT>"}eKB>v )i%\tMBrwBHj}: !%/8!!i !3%MR)N]脐Z {9)2>J<3>i&Y p^Jy>B4@eOlQ2KW IVll1<+}mi1Jꫬ_ K**|-1mFMAHlp@L,Ƒ7x k10 ;Fv aG~5t񽐾#v \&8\K+.0! ,>3&K.!{(M3ef5;k`Ǚ"iaǘ9;9jq\Ű:H0S 6!zJgݡOϏ(h5E_% st`(Y3Z&!Yv9$C.dm(:ܟ_ru8ib'zɶf!]eOqYz `+Sv+%. endstream endobj 121 0 obj <> stream x흉SY:F h IY564.Bu!'cmofIu]DadBWXrxdYxrɜXݪUBV ɉ!#BFP(Х_dȉC6jW(41d28$@7A?d8i9Z,.;WɭX6v㮱]̾!7r &_vi67yMB RkvvA$ ޣ:Gp(_>}ɾGK:yJ \E-.hjZ%XlغZR +GSmv@|խ,֝@&U7&|9{L[EHc $Pu,@SP-p%y g뺴qd\B㫤dJ_q"zu"&t]ߌ/RЛqv=;]d5nJR*G89`ETjGmP?CIpz]VD i2ˉ˦1gY7ߐyGf=Gwq}cu-[NDH*Ez5/JH," _ 7 h%R|ѥ$p8lm[fܵ}]%jJ V)AHGDuc45N*sN@bx\o>;C㤞VջxXN&I?@%5xfm$mU]ǂYIctp )5US\p,2èZ,&ϓOBrYP9`l050L=#Ҍ')8mZ@R'BG6=}JXE8<1 XKjVib)͑1 PX `p 2Dcܴ6wih*aZ%HvOXx(R~0"_& 0ѥUD~ҷ|9ʂݶԇ7&_F67DH +Bݨ~.3?~ ;-k|Wt.OgrVčI BU;jY%?~ڳtʶǛ|aFu0.M$vGV33p'v=]dy߀e|(;S'k\`l-;L E_Ͻ껾ؗ8Nw.T5{&4;"53Eʑ{*y0a yR̲ɓexW?E=wO0I_uEX>[B`gpb*zw\tPLfσ^H.tBnzR,'!VPHw;Ж&.NB]֑T/Qhbjs_=3|zj|a'J {ԏ_ޙ3cKj-T`xww&!C+`9ԁ/}e%0ˍQFéEF 2.sBgz!Y:7Uvg'wb_vsc쫮ȫΈg:;+O8 1!-DtOU8z6k49 "}p>QQ=5 jͣR"1[Ly+{SC|` b(z,H*UƧd*!JRMц\M0MZܱsc|Pލ.6Eajs~X9` bY|g9b+R㷽ቍS=&E==2 {+U'Fh!~70(z!;;ŸccraI8!L=g&K1arCJ i&_}$NoUqg~Fd.wCSkY]< ;ph;"܆6mޙ-S)^Hyx㛧zcoѶC+ a< ݪwІl*mi=6QMlI5«萜jp//6ڇpp#VRu-.8Ys ^E\ R,s*Ndjʯ1Q0ڮ;掠W|7 x@4nuKi"+ؼi {*ˉF@FzX˒a#|UM:\έ#E过nbձJXIf28:l0INT,kx;8 #5~KXL> $~]\{O] r r?x9"+OH~:,Zxx6aJH/UW|RNъ&mmNDvcݣ9_qz^xxsU+2@1`a?.t]wĭ" }r.4#_#H{:&5xUZ[F[b|||jN <|ե}77q /S<=@iDX|;$i`#ķ^hdiڥHys%:89K>) 䖯I"F4B-0:hǑ#-F:HdѥݍHPEѭ 8/x\;f=_v͸R/ω_P"fZbq)P̼R'}W~*"[(wB䄊Q,/"4P|VCxrXl M}eu]鷬I _֘: CCx4i׌S<^,.|[Bd @Yx/x{LUDVI}HKBɝngqq/X$! d vˮAJPkɤ?{wYrd5VQ)ck}EPd@—TVR!(-Qڬ"l!L½0i|𩩔Ki3p_,otŽ5TZ亷MNLm~I8u yJˬRt]&9s ~ISkY:6 bQ)69(pxl*ڕ,rmᘻW^DKQQ\ *`tKPB/y]Y Ka}R)uA۰PX/9Œ3P7^=5U]4׷AY;+NHߥb R@b\CCw?NGwtBy/"TBh&S-%?umbl!?K*oq)%r<];.ҫP#8wO])d/7B#CFBjɧڡ]b/z֊GpLiN`tl5cFJ0wB>dƝ3mStYaC%ەo;fo=&Ip/ +M)A#;R,L65&36 'gn~{VVi ZPr:v,߶j2SqaUXCMYV&_N5+R;׷ ^KO!'B@db2>hӂBIf^1}s= 18-ыI$TKBH03AQ9ȴ)1b2ガL޸g2e["&lndD?1=LpdF ]y iw3M T7=4y:~ws(^Xz$1Ejk oHI8 zzAR4 }t`h'VS31%qDBXEhP6REDUBjޣH&N YyM-Py\>?Z <M;GkQ}%N:s׍6GSjY0 ,[=nÅ:޾}} ÷-J2 `8ܫom{1gG.3BH=ٸc ^5sxak$Tbs_s!h2b$4Y.O?stk$@Ţ.'GMh-+0#Js8n`LJ&L+MjԊPPSOLd~>n>c[}[ 4M™*f_ui?]PGH *Ek&7.d<2z0)}wnsFF0~PtO$ZjOk!{O VI8EuTEg8ORY8>5y0ywZT\bu?js oޣnGxJ?~k-3n >Iݓ,?̦I${,\G[>TY?t%8@śG^\}%kA}cq44wkQ}rѭF8Bsox(xrY<'ɍzԵY,\VtOe=>9* _}$*֢w<Q 5#_`0shU6՛0d@ԺFܡF[5|3e8##o:U}s߄~\C;&4ڜZfoa۩5_)aNN +{n$LI㾿nҢIϼ\_I+*<_ :]6t'W6ZD- D0x~|ǀp}wf]ނ䢜#%nH'{#Ms4=z|{$Lf"dl$'P.脁k+C?ãB%kld5#OHo_#ɍs?澘wfqR9C)-){#Vډ4iYE[]Sly!=\5ƉMOX9]NWE26 1:bW(GpiA*[gσ 'SrsΙ[Ie ʎ\끵X>5f%7j;UB4@HP`UD] 95Z 6N9>oJnɍQ $8QBim5T^$5]Wqa0q?%^^!Wnh>/;/;ozwhK77ZycGI_C+4hM{}Bn`Jo"2bf7 C3w(5Ҷ嬜灭ͳVsJuN=5EFu4iŌ6ϚB:#(o{ct"5$Zh۬qLCCV >Z'Sm5ih4p>D5 V'{ Z$ǯI>! hB0{"&_e(3SВZ(liWL-/fT6 -@|Z5vZ'{Y'%B+0Jg fih`mlUf V$;L)mMM>BkU+64FPچcdi, X=bEێ=6}JYEZh#wЛcO!pjM!) QG "'~;bz5}q"S1r>y6Uѫ)K[e8IY7'HZ_tjp"dȼG % $tXAMo.aMNT/oyJ7\٩ D/#iN_4ڲk$n.R#f^D-АfE3xv-Wc2G=KYqnmPFHuVA6Խ3"Hm]Uzxbls^k!NJ &D7_"'7Atkud!@[8soDFQr"gU7SLjEFrUD&?ϵ`_Ϻ=aRTZՊ=.zF WӸ4]?5ވʝR^Ƈp䚄FP('_z)D?iV7xVL:ݜ&NWP<;Ke 3JḐUd"%u5YP(Y$*QҎ)_]z0<<,BH3{z - qNBfQYFA@wF!:7&k^c1gk2d{0^r"z#{QP+Y.~y3 >YijNV=g5#_8ⰸK]$BGo|<4T gf p=D ?amcEĊ7w@ wN*! ǂYp%mVGH)\pq_SADH2:%qw_FRd UB-F ƒpSL&ec\i1OgISG*fAEDKEҌ~f Rcj|.HmYEDEL9`!TlnVUaPАc"uA;KWc`';xʆN=1qf+u)F(B B-2&!Vαy7 LZEf+q-knDOY*` `[k'/@ cw8Y/_u_ JxHŋ5)-"" Z Far:QpU 'WhAUWjů&Y$d )a!<p'n2.uTQ'%пri0yy‡- +03iCx2i yh'@[mMaϠV lQWex&!KSe #V Ձ}vz`KqdZV 7em.Bډ8yc_ )FVRM@ĵb)}ᘳ| _s =]B+Gd?nTv7hq^O-<;~j cӚ&-Av(LdrZso]_9Lg ө_Kja߹~+"W0+w.6= i|)q]+vp8+f^yV5'0 v2T,.h)%ٰ 1>#BP F*!Zq@QL20aGKz絺g/H'0/9 endstream endobj 122 0 obj <> stream x{pTR0C%A<3eQ[I"AZhMlmkh;jʳEI ( VE# yȚfw=w{:d7{s6sT^ tU٭a_8u\Ӈ*~?i"-s8(>ϫwJ }ؿG#AOҊږ'дaeؿfmf娫a^AȟQ?pvR{cV,u:8v(3jIJ8n,v<|(ڬk$]$Dp`Ŝa.kYbGu}a_qKZR{pd:FXuq&ai b4 3z#{@"!)dCc#ΉZ%c@Z&ZAr #ΒkS:;򬘫/ңm>wz2weҰۀ)&Ctہ fpm~@纣{9^qѿE/ل 5 ǶVAZA|! )&J#mEF)D {48jjMѶa[ZAE vW̄N_-&Bj4X&;Af rMM 't173dNc}lCq.hOk[ &J#&JؖW=J6؞VIМ(5 U)}܂i$͉Rڜ¾>SeYӓb7YޞbGȆ $踝BI_O3m)zzUA_ObNJ㴚c<='c.F`P%!OOS;cj?`OOUv) (=zӛѱ#jvZY'ѱ#fսa~%F_aGc/Gi ?< ;:vhi|bYc/?ئ̤4Pӎ̵OY@#h}4_^|^ L49Sm\2Cb,KvnmoMcr_J'a, QyKB~j}_KY3hŽ-]@(jU3oϧ6;F6Lє])ԓJ>Ut}>wT%j {{ۨ3}=r)KRS*F;Lޢyt-ءp]tK4`7cOu/#5jÇ[3?f* ]]q`MY01QuQ`+CJ+z:HeϓFK0f.YYhc) zmk?cE3<< endstream endobj 123 0 obj <> stream xnF}`>M4^d;@Zq}ִ=áۀ1V]vWUOðcwՇj֚X]kT?`WP;n}rf~x|[__ُ1\\\\o.g۸[z+ۡ^_G7D;~.>9_ݮV sqaJ㼹rs&v~Z\߫96lխmvh44͕Ͱ5 g]5ΆpD:Mrm.Oczcut교v~1.o5BYp{f^~z!{zK SWVەP݁X/rqReȃZbK˻O^+k~6ve6$:*АݤnrW4]Y'VpIZiɔ&1G>KD.+G~Jw O&1]@3v;Kqd,JUd5dök6io+иi)"fxP v. @]%g =#nٞ _j@$ىE1ZYҢpZBG",4>DZ"1&5BW!7ɠQqNc`GaÇVWﳗ2Ԋp2;%A*cw7%Hc E(HDD 74؊& zB.hd36zP;{mO$ӶmmmAۓb+/hf>!)~>IW{% #R 'RMy {v^ӏnE*(h#9( ѽ紐 "iȨl3= DZA>&In$}*wK0${WǴm633̛Sak+DqWj>d /'7!] ̗8 Q5r=nBZI A9xCTu ku$=}g+J`VR1]l?#D4J}q#A>LI+'E ./xxe_|]\I'RȬ\rRsq-ЭFR`;.#(9r3Di.[(} )LR$5n/\vzfl.d/ ~; EzжV&3Ӛ&CLGW4W8TGs_Z_R.R0K0e|X1#Y" /}3\C\]QVуf &\Y_q"}%PwB/5qZ V WS> i@f%r(aeR xq錂!lTO"3 ѫ9K^TKWOx|FHo]K,ig3Ly%V(j"`i, kE.,g z f Mg{#fH$2wN*r~ń`6vuJVl9Ws Ӽt,P.1jȩF2NqAQf1GrsyFMO\^@L3 %^ʗ}S~{8״r4Q] s&V=KFL&'4#~!j6ZzxfMwXL0umm}p^U*kmk<~>TvhF!k^ߙǷ]0oLFGl_[;gBhhioⲯ!`W7ԀOxj԰s+u{j'hJPxڱ窣VVݻW].־~:E__~y/l};6⭹[ޭu1fGm[—^Mb ;J@]cm>+5gnk] endstream endobj 125 0 obj <> stream x}[I^^Tθ鮪,e1(tWuVGq7VDDI;繏/C:{9 DkxE%T\.JQ1M,e4BeUad0BcdIʖRw1w!Bfd82rE2vu,z]ܛqô)_.TgJ'DZ'n_?[=]V-z Eb:A" )hW2nD_GߊL?lEn1/%XŪA"YVqULgkF+*>mEo@B ʝn};ϗzxnVTNR"D8P`G!0s|-жxX 3Ԟ9*(#c@D yVEPpQŎvuef+ VŪ뻿XG%S G#Tf;j4 nmN^^0-*5rIR^Fn !7I`xR%T%UR[O)TLLSY]tc8uSN@Aw9BA,K%Bjу Scf rK]7d$N_Yx>mɻS/ȳ^LY0?6Pгb1x "DVֽXf?xl qc5r3^"A&\ g^/ӗ5B5n D "4CkДqig3|:Ez"mv~[x{Dʢ 4B\YcŒ]ȝ@QDƲThc8? ̋htz*BQ:B!N\ ;+gt5M4ݰ0fm"D1%ckDuhYTAfmd)#^@] ;_uИgLYOEj#ӓ *AqΟ#,?Yfw c̔?ݥc=/F703e#~C8z"!G6[g:MnNPńr]1QMG'Fwo[n2q5B\@PôCLv˳7,TOkfصF>mF*UQ ~y*wX$v 1[b2*B s'Bcgi"Syt`ߠ[3Pq܂@=d!Um*c qY'-nj_aXXJW DLyt"ǐFAv$]?_ x=j~I5LU fIt-.Zx>8sX|~{;ܭxldu͇j#47 _fd6U`_ zEXbęP3~aYƵyӐP5Sm}//ՎfbԂi홊@3j5#:}נ"W#QLp<۽)_NdKLUzǟޗ{t! 'x6A@k͕X|"TPi?MWBT6n)ff z҂ &G QTQ$aqnQy0T?t9"7ic=+S/ypx-X]k|Q|cuixb[~a:d$LpqupEϑLW2\jeprP6?hkJE'J|L͔ $-z/ȼcM<S#=^_anaimw:XEա}Vx($m$. dw'mpDo"֙[VP6e#l3-']LhE+kz:_>ᆑP+ʴm.%=eҬHX Ol:򓡒YWTա̋z8I؉Ū%w^:=q⣣fAnaNdf6N,=}5s;B(ž&xyA.YB"iN.mL~vC4Ch(ATf$ꘈR6krЫc@`ָ66V/!3Xk-> 0g"OF4qz%޾3lۺJJƓyxCy5ƾ(˩fg-c̿S07ȭ$qyAF zR91vރߙQH'^5ab"QNӃM$aWTětrWni(*/: 7M\nLB9zT.cgMWbA6z2D )*_xte6dvH6Q`:jJIYgɆzb.5~u͕`3GK fYkR0L [[p‹mD/1HaRҥڸQ]erW7$L5zHٱ5`\ )qbcOB45x`hK-g[i_9 YH@ANr,Vծ1"RƓqӼM. M&A\yvښ'mο,Mt.HxbAýM9 `o SݞXSvD-[lO59֊ _=͢}NFח*PO>T>9/h)h]'z+|Uk@&S԰`V/(˚Œ/ tu&W*qA)#j P|!$bY*"!]*UՄZm}SdScщ:k(|)t\t@{0dF5R,P^t]j9 &^p6f͇p񤹆P5i3+lL{T " EV֜/TBӻE΂gf'_~sŵ)Ӣi89V8xYFBpA 281*o;-ȭɦGX&O^^L9taRoZk[vLO] spU*GP VnZ%wWb(? N50p1e0=KP;p]t^҆Q/ X{7Cn[eW@-A 8bN(N8<9C#°I5A]EaxW#*!5PLF|R8k r-' E4'b dLG3*E L!Q9p/ WwD\T UJq/\{:h#oO T|S9t`f 4Ӄݬ .UFjek^CfU=Ty Jv$/ RZMĮN|ܭ̶g BUzs]ҏ>yw p0QcOwtM'tB-22]Xݸa4I?ʿ~*Sc $"{iM]Qx" 5>>a"'HËɮyjCτ淗P$Zk+*-zM͕w mfʟf﮷5jukehvomtzcN6=)W_ʼ\]> 7f^$,b(1X u]P Bm'" ?"&ٕ/Y!t-j;*m5{uBC*5I͙H& m4RٚWl4׊t`h^{إұޒ}wMkUq[+p׭`H (~"4njiNȧ,Wô1W0LXck𸫊q8j_ŪKNuEO_]U׭YOTi^=)QxGAϗʦ{HFBƞh5ьhnSTK™.6:иSKǡ0ib:g>x$Co y2<2rV8TaF#Tʛj^^pF¨.fJ듗ūaX =DxlG6Plr%iRi5j'>GXj4 : )$-vtyů+5yɦ~p⑵'t$BF4Rb@AH\$'+:L(qw!׃uc9Wݒ8YHh|M\s­k/'ܟx3oCk0 m4̌iv:0Bv% )vSc4PAc+# +bG;4khyT"U숁I̵ V:W\>sm䕅}e~$Ղ)cSjӤ܍e!hrDCŀrn#|#f+"1sPOаYM<p޸dB2шcH&`$(7&6pbYX43Í p ?]LX-S`Iɵv:6)-EMHANBLfQ1k/ޠGN 7G kAA Jk>˸zDX<x1̇#>=ĩkP t71}eϜbg?wV=X2_`bsyr%mKB Lk~J@0 wnFH(Zh XtVuo~ !+h.jQE(8% Z^]K,7iPH+#%8*J_ b]bcvr\̡ X5~fY]lK~J;YsJ(lNL\# 2_!!O0)/]|=͐LXC 6!$ÀAcj~yx p!p޺ Y(-f (P^Qu1TC^H< ƍ\s8,nA[cA+Ki>lve yRMخ/!䦲N_"iQ²n4ͤbYL3~)ϟLB4˵O6u#!1S~aYjsnOH\,kF m4.[2Bh(ybvcE'C nա*X̧B`35NeLU×ȷH.#vid'(x .*z":W@>A-Ȣ\#)@6?c׃4NO$(@\5lù%96ۗrP}8͵0-r0n ҧ5^ ԂT$_Nݢ,trY nc.u g9X +Tm"}Œcx b I zl5q!zr f׉ ZMO_p6{Hcd+xFS[AvB l?B+vUBUzB󼽯l =bp#o<~s}U][V('mk^" 챵V$Xod,S1mnb}AJĊDnPXъ*BӲﳤZ^?}6)].sQyye[+:r**Ҳok.P<|*9k;xYŭAHM!8UP{tޕ|f#]*'m&vG?/COw?b{?.v{ qu $aBl_EvM(djz[Kto. ^Q3EňcHA0@8k)?XY^=?x׍ t3L$!0 m̂bRɀDiVıӂ`wx9 YLm/ݱB+*+B\bQ*5**/߼1Sؓw/S{TwݢE5K;ߒG z"B8Od))Ws}1>r,aBOF?r3|ד*dj1WPb/E錏˦{-1 eÁn;qS6yBX)&"_ R-Ǵgbjgw4F,W"ZCw l8a#~$o_kq( T/hfWg1~-_bP.ԧWPwwF4}=4{4nĝGo+JD@(Ə?ٔt| PɮB )CNrhۍOHqWv%g B'L1{= ĻJDm/Bv HOiԸj1?j{u5~׍eQ3? r S.9ungAZY5)l: B\DfQPLZLGġlj,@Gk2vYJ$a xw{'Mx|R^(jsoO~ }IF1)r͆xw^Q+_+6B%:}:3ZCh(Q7#Ͱ` >L#4ZcPӶr+rOU\ hvoPL5$iW-Sϔ?4_B,Ԕr#(P#WԦ,Vٕ>F;W5S-0 N5.b ϓYO>Dasi^_Z Égٗ P]ŲdU?đ99E;O͔?l@T@&Iy4'=-N\pk%$B$bv` P'ie]iDWDbLy6\'[ԲAwA(:,JhO)a2%""nIa[ʪZ:bgaS+&6Ŀ΂]B[KЅ L>D@A=UU obfʟO/h65,i{Iυ߯'?DDuKB( m]S-l%sY4܏JѴEj:`^QjZ0 aVTֹF:1ƞlZ: ^(6k.]kovY^,'iڈWv^_^.O*< lo0_g[@%;7炋:aGKݫW U/%z0FCd!rTwmq{U}$D\0 1(G/ Ͻqht~=vnO)!O*x| t$Ie慄u&Q p9 B4+:0ɮ +6ȭ^z9kݢ\y}q3 ϽAkݥ/J:bXMXG!n4 |j۸w${v*a*v[ /8;}muTg^(6ūӯ{+:TPvmg+Poe]1q՞̭s!gKQ.u1uNJ'vD^ąGb9jO)SOi0M- [6L ׹lWlzbv1S`SPjjj4.!N#k`Uj|apNxPtbHCrh/,+!5 r~ UO6$!6 IfmC1{FYyvq+5v<_(W|:c{G,=Y^jǮf)e 3K2rgͿ:6 YkwIA *θHFi)Q}}>AY5k}!W|h_G2:,+Jڊ S3ĩ^(a6 JnC S!qC~JfQ6uҔ{>n!m qu^ GN@{Cx/' QHMNЎDo5WD-rE#@H;:a^ ++$G85%A!ƗO0]:CCt!IY/ N.ODkS"衿Qh|LnꩫIŽ%9-}\.iu{N|<#+rt PwG+*& '"9!A&[ [ i܈R^6?x||/RYC NC׫Ux&\Ɉ[Ma oU҃zAkVT? 0 0t+g⯛ Vu\VE~"cRlhq 2l1ژ:8"t\䎰'ܜ+e`.&1 jϜ rU&̝  _jGo4 b2v/u0P;my&)>qX65oD%Q70f31pA%F؎ [_A99:EmͲu?0D}~? De#vQX9g,d35SUnHI|3ZR|kE $NF02*\ݫRֵ7"_*G<އ.S8% + E YWDU@N bY/CXbgNO:p~=('EDPw(&Xnj2bOEUAn[o@hO{?-v{ qu~x6؅ jf!#;v1NO׍)8DC!FrGvTR{b?/㤰ߙ)].C+S/\Pw Ό/g&pTªo#]5(mSdO/a IU/5jUr{K]18ۑU3זe﮷f=݆"0;"w.LNO*ab$ާF,D#Y" T`~ZTFJfQ^*Cn$m0@ 훨͇"RQ!ES;lrrcаY̿EFDy j0NRGg"nCOי4e]$e]Q>j-WK,1HY'iEYvǵRYi.MSsrH2N#L2D-Y/, 1XQ> m%a}/D 8_oH']=bT.|TN]^G6͢ py{t &\qy"nAG@'6h6 "zIށ_F,KtzBʸSđX%td}H P㈠^  ߐ슌= Sh`7n6n1aNۆ0Ț2S\NK3%K7[P[vh A~%ZZ~9 x]QL3+WM0օ! M޹d؀!_{eE~Go6zy4sj]ek!^2 7$~㕆hGY/dX.K={:-84Dbnu ,_lA_ŚB962!ȗNg bntu/ .x6NdQP̢*=c\˕'/j5s{Iô}[N܊*+k{򮽯ӉkiԜD 2"T+A_Ae{!7+̯^0ɮhʺhd"̇CaW3 |\ #&mcLwwO]Ybrgʍv;sCQ"[{H\624`zRig[_I,% q-7*O_կF}`AX!joC J9S|$! (LyZ9zIJFϘ馏^ q_Wk[k RԦ% vcQj})-['G.S[W2_fﮃ,*|n1p.s *Rݦ&t 4HTPV^!*p (Ka/,kM?K tVVo?ZS0SHYkwmek4„פCo1Pn"t%\LD $6J!jЍ]#oZ؊bK_͸M\{Ն ?3ׄނf2f&՞9rDg*j14O5ZgnHܹ/ /^LjdNc(. `M2wUMY Uyû[͂$uuFh~m"_[LEpBqM| B:u, nvDI(QxdeDX%d:Eݦ YyF'1Vh~U Di #TCVAִ+7ԼX=`8i3oO*qjs+ S> 8Ŷ R٠D\{EY7l7Ձو ФZ[SiOhU ֬+C|7qy4w,f7Hk3k :_FBtqFJWh6(Z0^,u]5g%3aKA&ob(hdf.YX@2b@%$Q!dtgX; vT4d6ppRv;o-ɇzf^X#4'du=0HOIC©kf{&q[B Ot/Y9ճ"s_0^<0.ƳL"A "2O7aS'5˂=̿ոSέOt޵O8;O( mG(jbq\Ur1vuLlxE!a'nXo"c'4VJ2K1{)^b`xt-iSXoRy %,b!zӪNO&!O *H+INT26 !A+̀׀]RӚucݰGnn1.v=z D=X.'6E:pZ >Z`Dn G|Zժ=I2={c1C7-:o?`f_BF4h1K[BB.; A<*|I:zt3˩=sm#o9S::rOClm:秐-nn֎f!eҠr~y=,0. G%6Ph3 9}?bݥbn줯e|[\~zZ%gN 2)rOɮHB`jG+EA)OFaEn.|YJ99D4$:9(k ?ܮAAȜyJZN?QjA,a"BUe5CA|Di8H:W{:{.e{ *an{Zd"dDB}iHR&kdRP'j\π;atmAƕgHr4?}C ф: :oo9hg͎v{w~r 6%#ouc@CCTET:AQ"cJI(Np_; !%8r~614Ӊg|,tM]Zb(V$mXO_({{BҦϝk&2wf%4p{YU[N'άȸȓٴL7a93%Rn00t-bGO'FVUrQ8 +jAe#owNO]Y1 hL|,;|k~辻rLJ#ݥP .N{4B㙢lm? 0h_P W J8߄as4S<~zw_75E#rmp0xEoc~?չ,{w=Îdd<r-ͤ'^@ i /@mHRI%! 흠GНQ`WښoT P` VA% -S$DxC~J)rnc("WcNvp{w ") D[If8jmG2mtw^-pYȕ B#TY'm,Tʛ{t-Kё[Mq c?_N'vj9Ij2k ,oKN-:ujI+r]R?ɤ }7_e3ddXwXOX6Bw`i^pdkj,@7fW&8zWFd}lz4T |%B] wz X< Vv!^XX;;Fuh$`| v6k#KQ BzQ. 蚂mSA?Eփ"D88͢UkCOe J {vF#DM(q7iȓH_Y GFt Ep8MtY5ҡa[+ uD"DJظFZ{GƢ.,BcΏ 'IAm!pF` Bn%m?OL&~_@%jziidv!PmP {xm`]'( }ԗ}eNzm"D8P{,(mפּD_ kRHP]Oٔ~nh67re#EG ͂Qm,ȍwX$ LUs+ LI6X!"Dh:T՞>;wEq}Ub\o V z"TI3Z,>^zXF@BELC9" r" 1$q!IIf']chJ+KfʟG]zi=k-)Y= 7>B_ DNl`a :]K_["c Ċ'UTxۋ.&eL]-r=" .ҾZӺX~~)Ȇʰ=ywQ"TQDGAL"^ܪzy"DTIƲ o4Fy^*K"D?bYj߃݈LPMcw{pk%Ŭ /h !B=k3+|,mS1R6wfCGܜ a`urj 0ܒd{q#D#?؄. endstream endobj 126 0 obj <> stream x]y\TU0 nKPaeonZ&id+-̬,,KS̴ s5-wE\Pf.gess93?pss{,߇TGaKEULZ6qWh~a1eL⎑-?οi,a4l]z~,2(z'D]ox[#ho5. /ǣ߹(oAoWͲ`(@͇U@ydYy" ohp.3NDcMV7Œ3zU e{{Cb,(TEƝ-{C&<\a2-kv-·Vzk+޾^v a hr"x1.xҼZ@Mdc獡ߗݹ*xZ7 otsݽG-$r>q_ ¶jk hܘY6_h:(@6 ۀyjCw1Q-ewY/N4I4P ԕTfٞ\Օ|2H@Ci!-!l[+Əa9K(E;u[^ͤIG=e6nyqؖ%FNz]_x캅מJN޵799EH߿SYHL$`,:uzrpp{wjZoQ7?ҝkJn>/.㖲р,5E8pp3y dzrs-'Fc-7i=ۤMٹB4> [Պ_(|̓ ~O6@otISZnz~zSyR-h d1ջu^MNuNolnT T o:U~=s#:]|MUH۳ge. ;U-n|(NFԺv 6 /u$gCkwB+z l^_1x͐j(r<R,5 I:uj,8GǒܦтF4ݡp P<5={}z?Q0sa`;']i#! Q cApSPlx ?A@(Kf OCRK+@.AЬ+Ѝ3Ź=a7, T01v8?;|'TcR}\_/usPlKzқ-fLJ2JpHۥTCVh3\wf&CU 7/^ UlSzfz ތsl[6yC,*D٬{Pֺ+1l ~ [ɻ᳐Vj 0*{/[YԭQy'^c‰AocdiA HvA1 ;M#ȎeoiT 5pd t < Zt0/xpdlDNcW[$ @Ƞ1"qV& #.f]j}scHI%b<Hn}X8 ߰M*OG5< D4{?A%64zVLT{e" *ylĆSA+Bv %&RECf>ԃ@̚L'B#4Y sD̳N].s5-f-F.`p`'`_%K!`G"~ADYMa)+:r&i31ǽ R:$:䁁Js-[4s  % +tT7*jqG ML+8׫wP$Nkbⷴ$CJڱcuO ӛq7E7xW+U\mY?+!s8, lG܈74\N|`KRaaG#}hfo*(Ӏ6B  ,tn8,450gEyRXn@)ӚFsraFkb"3 VLV ƃLMh ? " ,'.t>@X8H$iv.N3Y,`>rZ\s Ӏ7 jnSCSL/Jq|d~Y^\k7?;6KP_RSYG߳Q #Z3\<[ ![@ hAF- D7F(!bQ}YluYsMc$PPM%Oҿ $6 ng)k VxS<}FH~^_p&lblD /G;dyuF!60(Y<ۇޮϗ|\}k;@MRixg6*thf<vyEU?:wy<[fҨFːg=2(*@ePe긧@qgJAZµTnF=өɭJ K K}FrUҕ'5{sI*0"_PP /25L>gV}cnC/6斾RMf'Q7kS\t P/!MNE /8ᣞ*ge\V6xܲwݜԚ?,H~h@B5Ld5O)_!zXye. @i$҄lE犈qGz$dƅS n>&h%4@ Xr4Ho%N@r MQA#W'0./Y82^U{^~/2L0-4:d9 ./V۔cx^_M]$&lxL%aY` X;=/E w>PiE6 3F4iFA~kl7~D3;g뼧TxJ5% ˊw7/ROvyG`X{'%KXbtqv"l%V0{ǩ+ UVt:)Z]I1ّ$ǎ^ ́sx-؝UْeCSǩ%y7ٱ}pOlwYFͯ yDVf3!b 鵸D]C{Xюr09d#sdž|y5Y{^j/||D?ǒ3Z NIi/hb'x0obFTbҋڑW@;IE \kjl~ *H4']Sɂxu췡+n3| Aem̞h,zS4W Tv^a#AԲHt56DŅK*NȲ`b[y̌cv2>:ޱkB!=q_p9iuvvKV\h@ rnZu\LLΩIy*/.Nh,Ϭk2a=` KA@Ђ~.-P0,;QQɋOrGX8MbAUq$9scn0U[JE[P#NHtC  ր ZjpPv ^=.by Jo|ٛDw^fռd3.p[RQdPfaN@p{>lif60}]Z褭7FjZ3I78PL$lV57 TqioF1?u5㡍n`?1@7EF,R~{"8fb(? Fa&S4sz.[CK /~'X endstream endobj 127 0 obj <> stream xsչ7gB*?xIERd`%` so5q!,rHdccblp%Y9=,&a77Ϩ5Z<[O@cI3g>sDH%oD4>f~'GQ^3xٲaî;D}}(HnĺS=/g砠jb&_<̈ʈhؕa`S{MjQ`,cFh &,!+#6>;Ajβ:Z5U,1יg`Cwi!V+c8|fnVQ,cP+ěg0ܸюKS:A*YRf!ŤQ,0!Z&<7/k%Ye YN&"D8 U A-Y'鼠f7,,WN}.1VAj{⧬ XsD"D0 C,p]" ",,`G'cNE0A<닛JsD"b4RUD0Q}0K;(#caekbHD+ł 8ZN"f9BZkbq {M<%V V bc_PXs*n=S,1SLȚq9_ZTLO 6`-E  yI+V;bs/|!ʎ1QGs%ž>akՈY5p,DEVԎ#bcAMPm93'YA,$eDI-/jIq 8,c5 D"848"е@0_a11N1x T1Ĩcx qtskPU Vbv %!d.D+DKЌjʸRIwX}0zF옊uX|>jkٹWf ~8NܷY8jG|s8!]` "f9)_3qE- v.L`ĩwE8ZBNJyΛGVل!n3׈`n!F52|]TAqjA㈍νVR*W$E?&ND Bm)t'#^cLcuL(X ]>XQQ84W0D"ٱ4jP^|RF3D8׉{56-̛!s`t^h` 6>;w })JuI<%8VY}0*l@:fǐ 8D<PP0/#fop fGG&1&t^j(Ҋ3U9jXkc DiK޹^F+WU|s&O_@yE1g^Grc%VC|kaQ* 8\>ں$b ຤y|X$(*cG&>u=좂yku1. kj\/QX"ZXt&_y$I|ks1c9kNs^0!FƕNSs~^I nuw; Fˍ8'~-TʁtghfF(`A>`B 5&ޚE3IJƊ+61n!6>;w_mT*O$lƁw`C:zf*Sı{`Y=} mgk;` 3X,F-u8wXG!FFXI}uMs?־#cXȶmO{[;j V{h<FxAvD"wl tG4x-o >GG?I- Gmsx?ȾDv'%|k޸'Ү}XOO}F]Q]/uWNxggDHglobX~NF[3ܵ}wIDt}ݖSz{{7lF$֥b6*]8h<ة_?<|̏ebޑ\oEW\{ƛ]x4wqxC{b5u ?/%$E..#Fs=%(#? X,bwq^Cl|v ޳%|~[f2"Ǘ{ʪ` DȨk4LgIJei^D:6`Ѽ!L&Eo $"HrE`:,;uN&bcq%`C:Ș -," zJ0/#f9ƫb<.X#J`ղcϜ`8bԱf\gd`{u},YC brsW P rx]"Fc/;69.{`&*Gl|vqL(hÂ8aqFc&H̓1e8#XcOd>X6>_ tf271##v *~r};S(2XV+[yD!f2]|!X#QFHٱC'#s<,#ep +1r11;׷vĨcU^Rcx GI1 ȸREa{d5y1' ű` bH6:VqqnoSgNzFc~WZ!FceQ1A3`r'1˱ҷ]"F!'ʱ3\<$ ҇tg2 `ؒEU1lĚ1:?ua ~C$ @lɲ;&o<`V]XCGBOީԓSyhwĂG:DA% knBSԱ?luG, PxYV#,@!'_၂1.`(gS,@lzیhq)yV[gTi^*ʕ+YMWq|Z+M<@lY gNZ?t!ˌV ț0;T@l"< F! g.Ǫ kz4> #vӾgZtZ-W}~V}ptIRo 8VUXs<32Y单ߟ:>.0dw [9ؒET"ؙs͝N'% kbȺÈy2_-.``t[y ֬Ύ+,wW Y G*EE^(T F-YXS«:G32}6DɊlbtyZ01r>8f x*=5DƕAp ɳ_?/hⅣ.)1b'3)Nc1Ap-ʂeGKf\vcIfXόıF8609u C0fÙg :6>WRǤp:QxՐV#͂;NFX;Q`HlpW1we9#Fw׈`:h*Iu #`Y`&'ݘYds4aF?AΦ f86mD{d" ͱ"F 8;jf\#s [U2*(8bVO6.t^t:p"FMĆ cX!}0*4f :/DZ"F髝O4,|9NO`j 7l2S5NJp,lQjpoY0Ak`433 J@p7W8?espBs|U C vٰÈ`e;ޤXl(rq rL;LEZ Z V` FǴ`;`*>`c;w낤gL€M_|&<b˥_&烱dC"W?&Iz.1*P0wP0"X6w.Ţ`%/㌌e̫S*eW7W Fs.-IRٱG 8 {MhUƕ;"S Qk誢SA[ !hw.@9TĈ`{ϒc+n Fl1{`Ų]E.cR@"޳b ȱZbs,01+#x?1hQ2 1`hegYn6cMæ`(-1$eσ bo_<)l:}:6='b <-?ɸ !FU,iIh EFF~uH= b'K=3\lIEy 9b\df<h$cbq~u,D0LАɱ0# FA~D$H>u,Ǘr{ʂ>&01S0##?Ece|Έ#5h5%ݱ:NX*њ뢤m~׈>+3ZK !bRUGN]|}0V6x`e Fc9F֯caC,3BfỸ߬1~)bQ FkBXfzf$h"}q tUQcAu6"J_9;^Ǘc%VżWo$cW1V9k` F8VW w_Q8"fǏ13.-ӱ_8#}0 *m\y߱#Q;;Q8 e /.`|t8&dX(QPFABE"G X:@,l x߱#F*Ƒ\9^)^uC_fGK-D\}ǂL& `qw8bT0N1j8&yױ@"qY0p&њc^FR,x|{UQcCI,#c^ʵ1/{t: `4D/:0r q2Y$V)kSy1*Ymvh8cAB1El"I9O9A,8`@0[s{OYwaG<> 2Ee 3^5^\-qrU8 ;F,mڴ)Noݞce̎S_kb"ⅩonHR; r7t+aBo$ λ0w{uqh4JXl||g7ܰeT*L$bX<wk7D[kz@bw[wC.A"e&8phD"qX2tx'ؾ#z6\>NoM񮻤g===oEXgg'ht[{u|T'׭2$%Ic":-ͮ>ECWW׍7 7cm1k;Vc)bQ[n'~&O7]w<ʠkRT"px 4T0{Ope'x25axbo>}uU/z7د3߷lٵy]^+~) VEp05d,vn+яeF۶dR=?'/OOk&/lNgYugsW_#h>|4枞͛]9w GkfDsq_3ӯ伋(7tb|!`6vWv^x{!Gw_ΫWt`Z܀nޟp1W;s+ |`Wvp#:uE}YOy^B*-~dccO9O[A 4֪\'XJ0bT0N183*/q2Pv$Xb)=$b`pwyǼ GA0G8R\+"e8D'8b8ܛBЌWJ΢Cz~'բ b/|! q1/#F'bVEf29]d~,7w!4Ĩ`J9,bD0@0hh7ڹ =jĎNg{[oL&bsx\?6=v|Ǖ-E ɝ~A0cD &( W8߉PskbG?Փ02 N[4`My1*]{Bp:ʎyS j  kc͙ob`hS'1 FS A-U8“Uvl`ǚ؋S QtV<9@0Tsk.b/M}kD02Wv{2cHN51/ &yt} rU:QX@0/鎹P@bI@0ߔؠ>8DξYob/L fDge7\ELT1@0u D41`T#׉7䘋"bix aL\u"؎&8b(GX]eyˡlv͠AĨ`L>T= \A(Gqvt `3#ʬ.tau5؋gL>#E|ߦ2s1< R.duquՍ 󂱊:Z/;4dJ Sc#F5#;Vz]S?%!1%PbD0 TJ cqLȮ1'UԢaI%X@I"X Rv1x\ɫ Xkr=E(jk3 v%kP+1]_bT0FAXc &j%` KQYO_ٱ;<)X3 0ȱ;6˶V#F+D&'MЊՈ,#@0r3 :R5ZYc XHuYԂ] %3LakquZIJ XNgR"vxS.XL}W1-.ʈ'qØqV[ e,uI8 Ĉ`* `PԱrc+ `憡زcK9tXԚAًǤly.rQ2*9 A8\rs0Uqn T1!;$b`3^$ 51\Vp~WkVhwl1bϏk3W ,X@0jr˱*,8,ւߩ8&Tk b7t+u8]!۲qs㟀`ˆ8EA =b{b=AP"Q,kf`̰~Ƕ Y>ظq͖cMALPA0,Klޝ~s@|nZė~AĺS=~i⿠VQ/ڱ#&_ţqݺ?oU%bD{ݺ׭{];N&AA-Wx"xr],t_]7nްW6ՍX4Fcx2HҖ^Hv'1p jJ&D2h{@ @ FX݊5Q/T*L&aV0`B\c"]4nVF TjqSĽXUQFD!%w%TFx%d2JV'z󪫮wc%vvv:!> tUe5QM:~1PZi*&ѕCx<~7i7^.δ{ߌ"f`b1l(ex;]b '5*6H$rWڛV2b O,<kkk[vmWWVCTd2iorԱT*H$Oo7)M6AG#F>:Y?#f}gOD"AVfXMچ;;;]dbGkmoobRfbXggڵk⊪?XhGGǚ5kbG~-n!kc%kA7fj3Ko+Dd2iqexbGl͚5mmmVX#AlkFk(W}g͚5]wRS'w[~z{{kAiYBUYJǕn43.ˢ%K===Vͪ賏2|h[7'f߹9sV /\'Vߢߧ~+֌G fac[[ےuuuiڥڰ}8P' ^^7duY<'Vuj/W!fQsWW=Z5'FݢG?ѕW^iVVW:–8S[ۯ::\1̺f*ڰF"z ~!ٻ[W_}մRCַEU5"PZN0}8{-$ω]{?C7M bqz]ω95k؇uV3NokxH=hfkbjY%?L!AMIC#AЇG31[gn5Ժ;6mt-T .5\C[4 .duJ [v|ٛdž CGIg\8B Z_v5k,櫪 dQoك2U'콅w}{ѿE5B OJV5Tl$馛z{{.nVjݺuAyz endstream endobj 128 0 obj <> stream x{Uu 03肁*(y **! VRFcSc+,6.l?RVcu(;lQc,h  \Fɕ߭%Q.TY`m\T*Xк:ľr\%$+[21 $ߧTn T$ǥBj~*`D2\*Uw ̨RQ`'PwQQaIKJ Z%.+kTYRwZ+-3:kUY`u]TX0X_i9T7XEX_B+˯+-{0 \Ż3.g^Qz^/WZά?K<]\UXоx?W//-xxSE J}^*,b i?3 \jQ;QF.E"OM2p]TbiWZTLY`If& TQbEEŘ6IsEJ9 ,BwۊEM{i6H1tƗ컵J=j ,>CiA}j*op7X ._$z6\|wgXrfIqim7e5ΌCW~Dc sԤS֖,WeKi%j Vn%qd^!*eXUY J(,0s|[y \Ua|]UXWO~X`ƾin pP f1ثɉj56,8sHȰÓK5NbBX`]Pbqs," LߵHJBEqR JM|"rbUHvPU\JEULzYjPY`_V>,5wPEN%dNQ][N]Ufi|uHn{vqIK Swl)}a:(\? > LyĎs 6I!v6kgo'dʑ*!bd0Xd gN agW4u /E'eη$gf)᳴y*!"ذc%2k tW fN{~9vU][!2o+=rPl[n\԰U%\ٝ]R.BͪgB.>Xa!^\*&˜Z^H\ oҨ!t9%-")D1R2.ᱴ:6lo.vy+#1[7|fp w1Xv{,ݥ]a۝cM nPXۅGv앧<˼Tm^)˼.REe~9". RߝEe~Z1h̺"2?<CN0˂^9_\,˂>\.(˂?'UHfPr݄1*F|<$v N\(umP\YTH.֟W e1k.5Lk܅e1eYW4螉/u\q1t1Ǭ0%3N%ɰ $3F%O\)ղ%1sc3cM\*23i\d \L73qb8#67AF*1岬Ai}~ Aetӫ]ATeY S.V! e<"צWdS59;/efWrfѤqF4ƦM3eD,ʪUr<*mW\E:Y׏/(YĮ-FޚΘ,] f>ailwhpGzs Yc[}^KKsX=+%o^#ꭥeEi,?/L۬kWu %fQ1rٷ+I+n/NFa*dc[_UzWC$DSrQۖ}vWQs1gV{*(mɾƠ(Fͮv"RQs1eLq <%3*= .,Eq\`9ۈP 3G\q2tO`"t@#OD81VhU]LX"WA?/Įb&z!&_}X>ZUzf^ta?=.&*.,㢂8~QJ&KT\#7f&c#+J'㥂8KYJqSAu @.W [uNt +mnCuo U\Yb8xX]i]"Uz\]Ynl47~R[ā][zE㫂Xs_7k]XbX=GJOVAopcR{:Z*=5. ,s.qk~Z`;RRC*=SvW$DѪp=!*.A,w%E1w<[Uz*\X29*cgzWкJϔ1{Rr$T$L1Svwv1?9.:ɬ-ĩsaٔ<1ҏB*=.,T2K2Ua9ͮ-$U`AO\)Z#(O`?*5͜WQm)%9V KK*e瓘lDNDNDNDN$ii{7PTrZGGGo{Q}_ޡ@[5O*mm ٌwn6!,s.?Uen=}\釩!NGf|/F8FYP&W( 8+4$m_a\b,b0sن8SRJ,_;}cD6.dSGʨYُ]0gLJμ,7\wRk8?S󁩫ӏE=rXNYfI{ܭxӗ(zIQ&Kx3mvBD:,_Rh33f\-2kИ|6gaD\8k3_p#<۹a=ήbq?ۀM{jkkkی5GwR:g!3lKpR_: F<ڔ-8lw~W3e bӈ1˻zwɱey|`˟گ]*q?zd٪KW=G՗m',۟f×O_+.x1 }.\ C]?lh1<glu5VlYsccr΢# endstream endobj 129 0 obj <> stream xooFߧו{mKQ$BT"o@ WKșn{; #̎wwyfv_qys߶śƻ\um>\{xHUٻO/,>}V>^tv˯r[#u~8y󷧧'^|~tWWWNj3wv%Oj~+Pط.{_?WÝzV?l7]ן_5~Vc,zU[v 4އ1tUMM~p SBˎea_~#0eڅT$ˠ [ק* +t>wu[CCܐbOUM rW4HDLph Vو$g 4$Zq]fCDNFu[5,c!SW X+z_B-TIFliLꎄ_QWH+o}pc4V8Lfge&#lkf#lZ%2jsWȈ̂S;oN"Uw(="tUf4h5zE*7s46XnnH&P S,b#ށ;GH4`"&Ǘ2H`: BBbсㄣU#7uye&47#tI~+tI obuUxǬiv|223qA>Q] d P8ִGؘpJib{-qa3}eXA2*)c 0^6G5i{Lv?O9rᔒ)r.2#γD1SzGO Xf܁;6q I]f[c3H^] Ӕ?%{%M~@DP %XFACjWr7^[X🝫\Mv@dBo\m~Zi-m8S(\t+ و̈LTHc֔1f& /;c;DK]S+#b+'0XeCm9S]@fW>_#V2jޕ=WuT>u}eJ?Oyo3 9 {dG 5ݢiZfp[K?눳D/EqؾE/EX2]%0rGaҫN~`9R?Q*oM'䣲U oGӫi2vN)@d=׈Q>qtF=kB1v8zЯ7ݧf+N69f*Bo}/(pSg |-M| URښwBWo\_4CC®.Ԑ fvԐ'$(SWlvl@[eu rCZ uw.vc raaբ]rlƓߣwn6,WwŪ9. ~P#em+ᶓC]sڡ0;b4> stream xwfeOȖH+=I6&d6nL2b&DZ{{I,HjeGnrgGaI5;c;6ށ0Y)6:Fύ@pq{1:q8ɓ'_~eVݛ¨fUw?I2btM|:rSgppĉգa c;NzJ̯ wE5}5iT ^XT=1G|ƭ0rK1BY'&?d}bHDmɨŨ\ͨX]‰ڡ}@9qnL]B}aN~(R+{"B8a9)1Wg&""_bD{TeoڅayC\O@¸}[6(vƟsh[TNsAۜ#mj̥mЗS2_7?"W(x2oVTPsf~V8#z+5=S[X= sd21T"OG( ;mX))Ќ)jc8I!҆9Xu/k_ݦ}alE0U)X}Q‰cߍ9R@A3ݨ>5NjbP8[j2 DȊ=+}a<\Kc|!fsUꩆyB8~=Lnhs̹Y 6Uq"7J=PbܛӮl \L،1p.*nDglbNӦB\S>Q6q|h>X,veK9 |'6cL9a-nw( l\|ALجQT[&X,_rM6p Se}K͹O2*lDLجt[[ATO!uE/os9B^,U~\/3:E: bBtH}QF-g.ns ~+̈́:q"j3yAa6/3aNlFfhUPۣ({^ɰr-2arl2*UlBPb@оQ&vf?vfꅜg`Y`4&{O>N~~y-/ƍq Űݝ46C,Δu7aY'FU( %{3{׭04k%)2 Me, &oIf23LجecöA(#fo)J^6;Ӈ} h`6N! Ub9Bμ;}JƇue|\: Ȱ/ؙ:S'6kv!(f:(cU>(cX-Bz "J-lRVq e!p_BN  @IDz.ARY~e,z&+Lج}H:ך+lxkNd(8B*~I-j8T U&A20asE:v̶j( f rA1gS\5/Q7CYp*C8USA6q?/2afw̻J2ٶVO=({Qa3>2?N`5 FE? rf:͏2r}WZ<9R<6kklx(c|22lzwػYgm=:y$$i6:Vpո%Pb$0L'g6i߻; ld;u `N0pb<7־қz{{Q+NpwX(5e MEu+pa}B(cXo"O~;yWa&@[3H|+hvد_|q= FY0y26Ǡ&:zhOw7#[Yļ+=xNmlsڲ^|cxpBx@xo=z(ge}}'ƌiˡ yn$mۙ}('f~1f|YrlWWWcƑ^'\iy*fC lx8g,dbt bK T玎L'\fU8D0_ 뿞UƑvlݘ#˼,W I$+4`K4l6H33U05*US)0_Alp"zԙRzs٬ڗm|ZNAA*%zoQbNM'ITjԑ\:U _f^UcP  \^>5!ʂGznb@&:MBl@;^Vtׯڹ$gZ`{t砌b8ŵscԙP[Ͳ`$5d*kEa_ \)J^=3ڰu:[Ƀ9n2PԁB{`uFǬU+,K_<gU YY/$E.ߝ22((pB]f5D i"e{T,e^\Hh3tWfP8C{yD/>\' ^aaT$-4WIj]ak | fQ(r#K{mDynigT6\Kc|a> EwU,29\XPV1: bit-J{U+pǢbvfʹ6 EۨP}B-N\O dL+܂a EсȔK׳2w2 xBMl3a_#R%2 NN\ARz!o:bsEAB@}|zJVNFI6kݙLe疐y_YTlwQoΔ̖ڟ7.m]r eZqǰ]jٰYlF4& vn.g%jpbWrf RvhN1AJJv6A6["fݰY4ZDڄ^_X9C-nc۠,+_gҶƳ8 dl=KWQ, 2lJc-6-^B%rLmCՆ^Ow+T;,e,9s{i.1ؐ 7n^͠(2l6S/6^(̘y edleC ܧ(<퍛'Id UceR/jNnYf#M+W e?sڅi,LbYlяa3_aH.&#qDcBlͱD6K={2ʟ34-ɄUq9ګTCS(;~xi3Aa1 dج)g6 c_2|VNm@M:Ԗ( e2ls_D2nS[|_~劋f(#OlVN ]6K?@fTgť$.UmԮ( Z[rf zr0"6c"I8)W]Q;OcN>UpY,p1K`quB81l6 zrBhh,!Q Y10ru>?Pm2ROV%:f:&JT(BRcuB8a>k6C\T &i6px'T\FŒp}Kjh En1AR@RXWvƟ,%ж!a yIeu+PWS({ /m2uZ7 $iegbR&& +QuB8q#P:6/] E|fm:+k1C+hd,-*W*aXG\8\x u P9Zejb2Ň2|(1j9 e:+&-: e3}7HV6hm%x<|BRN}O&7~ኋ!(cXrzJ4 lwcAw:E4p"z̙v +k @)x{FF j*V ]'tg?ߐFL5nsp)tо AU\BAoFu EDGǰSRӅLpbz1ǓÓw .(#\xWo`#=plphH׿VU4X,viwk6^MP.;umm:e!y3C6Ćw:Fi欬2 M$ 7I<ՏE@E0.7ҽ RǢl5 o21 aCVoc##.(|!x3*$zjP yعhUc_'c?ucrx814DV6H2٭"HO&+B:bCC?l~_<44O!uc Kdg2(kw/;s I 2eyjB.oT3r 'oSGadh(YaRǢ,ro aC$B xQx'V& y+s\ zΓ1\%SAX-ȓ̎ M jqp*돷7f\@-B 3}w0#(vT|hU~ ԙ([ 3:ΤGّZ fFDޖS,>d atZ.WkldtoqՁ(wdНΤk[Ol"Xc|e*[G;sw/J\Bh[l~ \m.7FNCBwZ5fdl=JzgK&.ڷ1PT\AϞA ̛J yT(5^; e7ެj^cyz$#"i̻JV7̄e玞xtߠ1!IT BKwAY0K 9\4V5|bo{,SR@p]8ṣ|g}<$C@-Тr5.C9(n˼Y YՀFGJ1ad=AqHa6z0rЀ0huQyd&.4T$D " ڋP?3K>Ur/.w`2oFX2h aЄ(4Bw=jN@BwJ/(" &{N8FQ,I3/~+M۬k)/DDAd:Rc=V#)M|Ndl6{W~ 8S+LrLJ-ԆMkMlpp6lg y7 "wN="iRRpS&6T{"ߙ65 y'N?88GqB~Rlvww79(2PegeOfB^L*BvFntS|Pa惫\̻J2ٶFNS˶1ʮ&~ڟl6{pp+Ӿ'4cyR <壽257}6^\9S"e=qJzw<Oy+WR_xvjǡYT! hlH5SF̛8f\~=t*_o3s)(居קfP47 6#d;|c;j{8V>ϗc{e";1f8AwjDY0HWs:+1㾾>ΓW<퀿`AT( ^AAPP7i3OzJ2j koR.^zUu'ٱ{>㧋rG-- XktjKYl*}8&2+@s/Ǩ3 J :Fgh/T̠TAR|6[T3?W/~w*/ A.Y.mXg.[j?Mݑf;:T=ԕu>EQPp\gA-bQ۬ĠTAn|Z:V,[y/c{]f(]'pva\SAA+Ȯ*9b . E{ɠ(mb^3BVQT @N]N( ;SM?=e(d=s֌ m92JƟ7lg菐HNczsԪ5 >}7Lnh9rSsҝk7 @F $K ͠bYna#d'*5iK*'Zsf@;m>^̙zZDUj5 ʠ-BrvcQn O j#;B)Dm٬ayC2D"!cj*ŖidpƗV[5Xg~68a$E=Ze4n1/6,(aj2)T ^VAis, $ǖ6[1BVEDMA4Ce2l9csG+Ay$l! u|<.2}`[ϛ |g|.Ǵ A]Pv=PYL+(GSX=wAԑUm+te#d;ј[@LM=Y V8.= KmrS3s2 ԑ33Wʘ=}ʔi֘٬UP 'ڪ=ކLɹB`wʊ|Y65oñP8`*(Γ [&B&ܰ:Q"4{N@:; <[jY\ϐhZ]q15=%Ph&nI])n%caQy.Gf)ﾴߍe*BVkT j(h4t^5?ʖo%p4v 1YԴs7<ȓlY/REF ā& Qy1gJT4L=AB}DuL=fÏ*56&{pA͌+|Wʸm!+_AhL)cKi=SܿmlNIf Rύ9=BV`6JXDS6-ʮ'x283BV"R#2&lSH]>:{ܖ(B(ߙRBVS#j5!Y՜(ۍjǵ9"95;9Ѝ,cTC1.iODve+q]SlB|Ϧ<j"; Q;Tm2 .@d;B¸Ό(4~5!mg2q!tj#*f6C٥f:3BV#WS_ :V;j͆2/q O"Xm̺g՚d.vB؛^۔z _Fw|IjuF"-8pM_])3-tV;W &YxmP&I )7#YΡREadd[ m46Vߌ:Sh&#v*HK LP4>{o Ch&=H^F!fQk];S*N[OW\nvh+W6@oMa4K~K;ZهH8A%2ZFPv5НRoVg8VCC)06Ə^iVG` 7 :LB'EjT"C"ff̛Ϧ RÉ6Ə.5-2\1E |z:DȪq$E<,% y+JCGF? d݊(=}ڲ <(1qf!Mxd4:4wNhPRe 7|7 hV:O1"JGCي(`A Cj.Dje~wNx (-(=ßl6g?Y@1ۮJs296:(\.So9uuuw3DjW_zf"a=DY0hs?~OO{b7j ;<ֺ-GR49\Ѿe)?P}W̾~8}Nг*ixf&m-twwKpj 6(:7k6 3~ډtuu{;A>lwww)}^j̘zW_o̰ʸ{^x}?r.М.nW/^D_xӷ %ӧёQtt#HH=yRoɓg_xW|^{HFUP@I o}ޢ}oo'6z8zHǫ6 e#B^Lhۮ~rP܀ZeA8.ɣL4AVKx}YƷa(ٔx2DӶ0*{Ṗ@Z.AcI23 Yc0./5<\m ʦf#A o3kA bb\@͏2+ +Ie/dIc@FX,7ekd!-pfGL-""=_AT7M2#wНBF%D" j|JSo_9SJoNH,u 0`bYlJFQ&pБbf!GՁ*A\Uہ+>}7Hs oVefG0q\mBX=iQ&);5:Ɉe4f!/uK ǚEq6 F;"Wpě eA\)PP:\clFGg00>配q4,g6s8|_! 1ڳR%2ZK k6Pƕ &BִEP8ydjef''4&Bt*UAo* 3j>DȚ1TL@ބe"SsE=LڸAsE(?#R0]ɸ7ʌK<_.Hg37Rd-sQ2VuC([ ~5HY޸]ͫbTW(àIck}tqwY8L!q<؜~Pv̑2ljs|ůQc1P3#|Qd=Q7t[?g:SsYk9Q1#S^4 .1+F V<`6 nT/薷\LF92EL𴯂eSŞnc$wajl,;lV1=AXPr+;m? [70QHu6 rBI\PxW (]+w=5v!l6eǾ;S[ż,s˲}DrhG&ܘ@)%22B3FbLMQjv'lvaQv^N[څ,s>nB&܈]P;D#Qo)YG e6NĦnCz'c 4 9[X{ 1O!E- CHfrН2p8 ı@EgG!#U/&BBSYb#*C9 5eA]!i6D:(*E _8@Oj2QFFȖ *^ef\M6Sk ֑YȻ_H@[,G(?GFf]t(M(Ϭ @~|D1t| *WK^ )eK_<gDʨ5yP<~@eڥ<; CTk&`G(}Iś_ )|^˙[R F{r|OjL=WpR^J_Y;bƉB{`uK*ngf!D%ǧ5fs'B~<ߙZW;q[tc #@%{+e l -mT70jm잸!}x Lݔ{sߑd"d)c_" Llb-OBBwڴBΦhbf!xgz[2(ԏ/!dY?ebV'6cj۾( f RAןIV~֎PB6ҾeQ= d>1~cDm\ ŏl|u[9A["I;_ڢL/&sj1>q6ŏ?e΋wɧ, t?`ʁ PFL$MO$^j~f!Ke821O([q_L}YIG1P 0lLqyN?@4&4a>5D̻~ot*9J iu DU:/ 6jwٟac$!c\׈Trʆ! 'KoÈޫ{UjPf*Qf?3]\3f\\N_{zz؜^6QKa<3Ge}lNo_yL;6xlZj< ϿX*N~0c}$U*yjP?8ց4kV71s8llM~f!lvѰb1bĈ#F1bĈ#F1bĈQQG9z(oWWWſ8NM_ Ɖf1bӓl6ȑ#===]]]GOP&Lj^Q/ǺwE dڷ3-~@e j'j5NJF}I*>/~//loo/u@T^_ eԪzYYG)ǏW:ydoɓJwwwKiQAYww7+lMhwwwWW_{ޟRů;%K:+a9>gٿ/{zz4Ps-6R{{{OKƨ*m OOAulwۊmxCp/9z>KwGghܨ+E;__GſUsڷl65Ⱦ(.^R+=>>~_ǏhVsUZٞVP堌_(m|[JvuX3{z/ʞԍ/9e'OdHRQ)=Q* %p S_WU2[?[2:F5nF-s=1һ%u~JQF #Gy"J uůR4+eoFϖxx!Q)ʞyoޣǏWA# o(^El_QMX~wQV^kƨsVKq?~W^s?I?xqe-'6]zj(Q'`޾/Yeu=ȢJ_X#5cPq`JE_8lzË endstream endobj 132 0 obj <> stream xyյo8"l€h BLB+D[Ԍ&> @.$р "QwFDuvfTwLW[snuz9u~Uw=˲LŶ&o1']nnh$ul1:Nxim1nyS;upĦ:lxDi[Ͻa?utXXyǔv\& {dIaJ@d ^jl=Y{^aųg|f`:hw?2Taݪ0 t3?o8XϨ* 7avCޜp$zimnHtN3U&͙72R~b+VUP7g6gT\Ѽ0c3LXYૺ0 ,oٿ0W,nF°°vV|̥Ƿ0gð& |86mbz#L8Ggģ^G7&+^u#L(3zLaz°CWi~W ; %򹗛„9cLrtqE󊧗°/b/P ﯹ0,L3 e&hs S@aD{z)=Ϻ$XW ú&0UNLa@iaɦLJa(iase.};2X} a(C7C͋>mu083^[+# 3 ,Jy% +k|Pa_2gJg&BUw@Ê#`ufvWS)&z08]490\)oJ91@EepaX/(@sJ%Ȫ;^ pCڪ\6_9ߩRYZ'_'\Y9`sfW,v{IFƕt7(a7_/NF5'iXk512ozܬnӺ*)hX$alq ^;"QM Zs gj35ʴԈ,"L 0ǾN "5%FZ 0*{Unkb(ؤ^6,^3kSz%{ $ZD Pf;k\/Z5X a@3ZmAwќG" @sGśxfha.Mk9o4QDoԏ9o-i :lS4ms}waP6X_kE|La#Mii{t%ނ8C& xuYϟ@uV:a}34[eG`m Ba_ ?@%Pc@[+0Mh<$ľl  Tmxa] nvܬ<NjTA!$zO ũ0BA+Lv-$ЎI@DtF`2 GZi'LZ̥p1ٺw10'dfV8Õ$B^,2Q~Hӟ#.p°Ȱ$.F5\ӑ}&!iwa\@ƺ v aH3Pw:`Dk89.mߌ0bt\8' !a$T]_>PX7% 9SI3ἲ%) Ƅa=m 2)zI߇9aDE |%@Xzph[>hAa@өm% 5 Q&Jb(:[W~ʰQaW;>YELcgإҽ|*a'}IF*9?\:K+YA5_ cI #S"gxUy0=i8\@%,>(8ҏj0/݀ ʠn%ћ JD@ԉkψ@àlm]L K&#^4br8tTrej}8u9̥N b|<&~ 0kφ0GI!CVbEfXe}"hm~ZZvw@_Ji6H=i @λ~q e)Hc˔~ͧ.7;}ɡ`b8;Nex"tYTO$3J!8H-&&яK#.@=(3=ЪVy>4't(Ћ/C3LϢI}ic*| K.pi\0L&79O#lHx2e^ s*x?QE*Œ!]aS?7'W Csm\ׁ\ N 4{ 6}m&G`dآB@lt RZh<$XA\=y 0Kh§P P6l#2D V:<0?4?)Wh@X_='PN7 0bpx@#LuT`c .R C. KwJ՚Q>O$L:,t76zA{j*C#Ldv t}C#ī Y 0 U,Q*  Y+u{s@ke2XUpZCg aF(|]NEq_E ӟvyHRY<9W} Z.e]0M# %vfyrN`r0oa(u2Ԑe/kVfN RP/pSa% ;0fmYX*3D5bÙ na⎌o0lOg*w;$gNp%{ \p_0a(ַ|voQ% 1ea"d&}{ɳ}@AGJU"zV& [ތ &U|#tV55.RpyKH :Ml*MydɅ93 Sth^A\TsHjOhB^q0;mOP_..yv%R~?+*/201zǟLhvZȠ[@}/e-=JmFyNnI9LARyN/8}$㻜|zW;ߵ^sec|y]09]VM.1J~Xo'Dʠo>5K~[zF>CN]zV) sEDT&1^u@xM %ak۱Ἒp ss;y533A:-gtOKM 3yY367ooMK 3^༺weU:[^ͥ$Y 70|ZJ}~u sO%]~ avI0oO&Gn;2a}c}޹|ʆ.aY+ a+eR[vi ӻ]2z26\.u֧O*c=z2]=[t8\jUzc/%v}&guu2NQ:a endstream endobj 133 0 obj <> stream x} |}&m9ڛ8U4I\uwSNIݤmdζ[7]ljE#[$EQ$3 R$EM`ad%~"3~oQQ qi`T5z`A1 @0} Hj8eb%:+2/e>+(W|A . 31VdR:մQNp"BȠ]b4?1/"h4|6xū)W|cjچ3\1Z@2H,H,v\MNU .6,YzF}߾5 yǼa7Wn*ډrgADf_ZcI @t.(:@$%4DաBK+,i! ;M[ƥ&J+n";$<{Fu޴\5X3oZ};؁ph ")@[灊m5`pP牸 /FCo}^;Qk\vY{Fq\RD)P6dt{Ж[5Jƅ$ w:l?yVyＶI05 Ⱥh@'@0Q7?{MSBj x^}KSdӖ[徵#=;peі[z`^ٿ+=2v]z43Һ-(&}D4+Ybe o=|[ktzn/hK^[n[sӻ@^Nvncʱe-uz eD/!(A:}JYf@4+/:~d9B5%w%UքBUS(ț^1bY4e}n!| e@BLl :OP递8˴ʿl6#|B W9 Z |)4T+#p7w_fJxe5(K^1R$YP-qZg00(=zpQv ;qdh e4 0t|)Yq@_Z=a/ )G^0tb㔠D[h·>  G1,$(@D_(Y_p&a\Bq,:=L wNtaz3c8z rW0dnhhuD ~04MoDzjZ Ẍ́htnvV^XtPi0uF,n[!&΄k۾#,,3NͺX&߂m*}RL,ufiqKUCbbŔTNfgahhl^`Eyapp{U)BlG[j:G'ǼFkd|lhmh}YX⼟{ityX*=W^&Eyn-=$tMSGo641-}jbZYKK&dM 2FFlz,jWCG՝FR|֛c8P&5:MLb(KQh @i)R0>ajul=+Dyuq}EykbxBQI,+5CK[*'n^9aQEI 2JeasjXV DӀɇ)}}w'<볝01Iȥ[ET!xhOR@4kUPFbh8 . m`o:T4Vae:$`ƔĤA֖-onWl w晃9)7r(Y0 [_ l:Nm!ϣpV/~N@sHީZ] ~wbsyy\&1]N)d\Z!9k %Zn6[V-6n 'Hr!Ž +W!~wbnImu"`&( C&.^!zAhTBW`} 3n Y­1=eJOU:Џ*`IQ ; u+ ]VPn&tԽ !I$X_l?FIid $&;NL[R JFQ28"UM^t 7%1TF! IhK}!X`p(|lW7MJ/WS6RgQ2j$J 5F"Jd}+ā`e34@ga$:Bpdx$hl6 F-!1`Hz\9!>W@ZCW DgPl'XbV74/bPx6RiS:eDgD 6r fAT`>qi ٽׄ+]r0L74Ӯ< x&XH]z ?򬪒:Q(.c]B蹳Ǽ6dBnc ]PNr/2Juugcb .danäƺbY%YP DS:Wj6d'%sC=#ӳ.FZuP)m_GK׏Ȭv _{mLs<G";ND8u C{1z\Àk#`,rwdU~'S<rxZ[IPʥW1BƋboU3+~V\NjT)C14Wy^nQ CCՃ$Ƌ(9$p0MS>f*Π$zSPҬI4ujrd_['#z)q4>ҟ J4H(߇+Ena)eE_ 2Vxr  ^x kh U:hty+\ q=U'Y~s,t^~%Cn! -<2վZK,랗NNdž( Oi!!q1<Ҿ5=.^:htyK]8n8Kr6urg%K[jcbj 5ILe8k? Ɩȭ?`ZZ']iiz* Tj>`~㔆't7ߑBNI!9u}jJn+(d^߱囒l;5gQP>.;[R[Eɷ( 9WY[|~gshbFes5T<\«ʜPGHtiXY>Z!_[jn3Q'ozE.ءUıE'Ϡ w+CF'PTG0( KeZOLY/qIB{9y(oܵK(£ow:UIA`@8i1r+ϟmkyIN%D'u*_5CQ^ %zUu4P"{x@]nKƺeRz')= PBJKvDxtG]_|DA + -{ 2&'V?ٹ.3ԩU=%pFpY!!4@sצcA Bw.YO Ww]f"jkLC\w/ӂJo-cu_  DŽ[ Ɇv. qX)i.q **PK=!}o"TUL5΀0jbbl`cv$94jFwX[ z}I5 -tz+WR!!qsaAnk =s(i?Սc QV&l^%XTԴ_SȔdahH= 5}}zZn+Np{ncAAؾ u-2Fm]M&.lPҼ!/AFؘ'y^b+ong.lfQu9'hQ-a`i؍EIn6Zw CGv!Pb-j xmg@H]:uVOܩTtlیص]y\I(qd@(pS\*!9Ac=8pDncz1zv$#qM4*s őt8gNzlխNUh"PimQ߼1{f'`b҈]q|C)nT1Alp'&A:@.*p6 ӈ-,dm焝2q֊z>p &#HZYlTBb]7 Ԣ,ڢKfˊр邻͚Դ'dɺ R-R[ 5 XDKudMsKkty% c`pܚ #+i2*roxyE7 =qM%xZlap૷nĮ*&ÉZ!g22G\+N0hqܥQUxZ Qw8*;ACӾb)tmmOȸSʝJWң*AZEwn*<-y6QͺF2HŨNMvdBp/p{ ~!0 nFG'Ƈ⻄ .~['8& ;G+a `zԼ%2TN~gˣF,=Zqb b1>X&+1r~Uj b |k5 ISG^ǟmXlW-2`W[Ow~K ]z2,O/bo}pMe^>s헴W _{?x;䝣1 pgao0EGFg݂fn@F6HIIBl@j@|*d\7xRjn5'*Blr< ֦@v~-:}1X3(eTMעlƔ|C<;O">~/K'v|F'?۟}ӟ_P?=7O=^ǟ2ŗ?xMz K?~SŸ…JZyRtbbwr67Tμs]]K6ʊg}}sii^_:͊W&F^`l5 R~XnEVnibxBĵ? }ѧ>S{couz͖ɥsEuYOOKs}x+gs_9ͧ;z^M4ҧGl []BF6O }}k'Ų :{Vg*L#u!9uB,X4@Zƽ7dNpDȌB$ >>T "K_}Oޭ7y?<_L(*pL(羲6:…uen{c z^tMSg̝VM7fgg4!hu0|;ndPxkm &%YgtyqZ VR 8lNϽg~wQ UhtyΝ;Ͽ?_~K)Kͨݧݿ}'?7z׻~#eIBegYS[G+YaF@%tNƑ%n:׏(,q'ŢRgSAFUA} ŗr|Go4 c)~<E__<_g|{'ob bn)7y,vOmvYÈ}}ɩ!Y=ׇZl9NL9y en wx@\oG> ܗCogT&>7[mxNqTTtF\QQQGQ*]DWֱӱv4H!&[ȥ+ȥ"b5 ǵ:0Z Y+|Z~ᅋ_k/7>y<M_ Ф?w_R'wZ{7S<˺OK^{epqWhU}sțpla@@ֺ<- .ڒ[e+B=Z S6>3in~Q,B bV_7+~dAi_~7?{?2~玷}7? gOGxЕ=_w{vO|]FGG_>}^ʦkob_s6ln45m.gdaͅji8ٿÉN7 _sqn6i-}b$>3ǞT 7n15m&5.p0n݉#Ʉ"{bI@*8FabR+\Zr@zLN 3$LJZ,1T%@n'cb#_։Wj} <Ɋ )$hA;Xtv $ PDeά.-wd_ >W6Aeqy67>?sM ފLe _9E.޳~B8%f{z6u\Y8_p32yag_(Mnha0[@1{ cSʝ9~Sq-'%,a$k:Av &-n.-MmAP01D4cfǷ;wK؝.u Vw~f3gsq5Rsse 1ٞno?Yw:4,j5NG[!?;wo4{w˹%dvuMZg.\Ku@.Z &B}=k&ef@la-6 iBɻ3HS۶&UwHSJ㔑&kqMh}gwI[}s[P69m9#9sӐVȣAj:q@ .”Tp\ ! _֙[ɻR#78gܓݟ` 0@AT&-1Z U&U`[^j<{U?&61o-p0% ov jj-awJXZ/.=aLc{BBbh=O&a ٦N:|Y #2%Ly˸˝{{a @4NBV:yNt WJl V,9^ HN]SJ;i<cUPHWpe~㔊jZ(hs2W2)@">>afdǢiAQ216aɔriXËm\O" ,>я^Ұ <Gamd Ɖb8X=$PnMçvlqu'(a hxǨV;:c "ɠ.j}dil^.([hO"p𻄥1 aty}L6;lWX1̩hʪjZH-kDXq"^?6xR-6r/p_}by߼o,BqHAP_G/VCC6EH !Qj,DR&ΠF(7FIi2*rjJpbIG+gVX2d7QxJocl8k%X9 i.4ipϣ1/ jb?³!3{X](d~H‚͖H0aBC-=)XY4Q|b=RmAFhLa@$[v &󊆃O F H8L7P7vK.Ua 8?իW>Y &_*l(>ĭ]" &tϑ,L(+WQW*4Ű@믿#P>$,'J̧+h* Z'w8z T7<\*=;M1*JH-?lg_ 믿OlX[[zEQt].VSSSiiPbMM q]]]ۭ,%///WTTTWW5_trk6ɢX[ѽ^ad=O1@A/PqM[MmG,3bJK(w}{?>y{JKKGg>#|[ߒ>7x>?lXg,7[d!dZgH4/mŁ;ٰ{VÊRi}VIt￩6o3Mݥ7nDEE1 W>G7O~Kz׻^y啵5Z[^:?ݍ߹s}ٶqv&m<T2^(jk¶ 5eK8apگ]^~ҥK?Ͽuw[ dAl4Hf^#O54ys6[VHi?7^/–j=3_Zxϟ?]^{R/]QQQR嗿???>#>ŋz~N`_?w;}W:&BM 71~ԏB=bqÀwb_yv׾}.U8/]O.-- UTeU}1D@.ഠqb$3hhwb\P1RpcO0±x)UlXwR iqqvIipƋ.oAT1`; u*v U e]⨨$jBt kdE<0氽ʩpZ 9xsdymS;vavvv{=A띝6m333RIʽ'01id4$:U'iLa BQE #8#)[l1O K:JCW!ٳָDP^N? 卻hXy{I_K}$)T5ft]JkoL ALe3 Nv+^ { =щPu}\N*- <;F:J PvbɢJ#=%(^U֤GY,0`\w 6S΄bb=;nXdN]m]Emez5 jXD1bf *J$Yط#v,d\ lmmr2 ז%Kz4H@EľPRh?φyԽ]{D4ݻZ|k%p2^J*OO $m-G. %0,7cVWgFTguH ܒM6$%,AؘRͺMS4LǬ]9IF F7IB~ݸ:O<}5,E0BrĹ 6A.a븖ce6[, b)G }BJPqN- 73h34-B$ Krs 3~Tgfx~ityK RӘXJ#8@eF( 4^ڏ«̚T1`a74? $%m%d6 n7f Ox"5 Yg`uM򦖻ԨvP1@*o}zen:BBž-b2ޖݸ[FWqFԑxhVPN ȾZnJ4Ey#XHP&}(RGGHHXJreA'ȎQZGXvs@И(<8kMbno7==|y>1ѵaHJ9D+Jn\ vN>*( d@hQ.ٷ 1cF-`4+۷,Y@~]^$dn\ !ת_ PMx;fT LjAJ2 j|X\WNgsSL$6j** %#i@|} u[gH(e}/jx{}8=d!67 9fwqIkmoe7.Jrl1oOB Hdn,̨3_fFE]]웞oQ(gzhɟ=g%፹9` jF1X g>Wh7Ey ި= 6W*AE XB.'OؼWBgg>Zzc k,}Q>|$A*Fk'(ʛĎEf M‰:BT@#٘Xa7B~= /B3 <$S@7ZqΊ3 R8vBG)7(^fyP6hΛii=H e$;Q >KK1ڦl+a74 %`_M20jM /\x?ᙋx𬯋W2MCjpz$7ԾIMJ`@P?'njK8dZYJ8 @iffG?p$#cXS&k1ƊovACB=A@$?쁛 Es :8 i 9Ĕ]W_}KB8W , PD59۬k7n r B4A_adz| 2O|'t7'# !'`i`  d< y neƝ[BzMνo"X?d *$XY5I<},= qك`Az^Rniyox67o kyPήS-Ȭfl-9/V %r ˮ)h"R KPaRސ٫5|\2= k90ؐ";*VSEfxwko h[šH7nJƎ4Ov(1!wPk'OUU{67>XZa|hEsn|B/6)2;@pwǼuˤ^/10%MWPxtΔ֧VZ[RL.;蚦$_Jzz/PF_A '&9"%;8-wHi0<>eB%&үq/̪cy h2I6thzbPKApH=5* ,隋L}ziHy"GBP'NC*Ι7S01yd:nI69*ЁLS]F]ޢY8+pOߊVv$ Kmq#AG2@78g,m߯@sjx%cht2kRihW>qj j-tr2FS5m%9T솳jo[2[U -hbī馦qUkmjjcvvsaa}ffu||َ Ǎ< R :)U4,hz 'C"G(3yz^1V?,iNnohʡAn0MFIe뛧QPp48fn65Bzȼԝ % dd 9Bm-6zuNvnnx9…7Ш+ind -PE* Fehda|fBΑi]vk\ ԴQ։};$N A^[P'4i FR:V mr^WMZSoi%8 V5C 1, 5%8zQ2f[+hB3'┠aA\9!~9"|x}chV X4"Q={wdtzjݺM j=Px.k@UΘ%^ kn - lu&:_C% vόQWGp&fgߪXv1 *kr<( vH.UA| ΀$Xpvjp1mֵ٤2@J=D讍)!+ M$Rn5E$ b bndeBpvV26T}^Mj(@Ґa}MH@:8'9vwYw 7r'c8HpJUhRfM2YO@M)K:"0#)# OWrfy(AGu$ c "ʋp_' 5%%eyp"5~`4+(^,g5%5Qçh+p`ǑES;U4'`d_$԰0 >J/<'2.MT<D[ endstream endobj 134 0 obj <> stream x흉^$}rB8D@@HPX9"! &P K J@DHpQFȵȲ,AE…w_33/5=i=pʝ'nr|=!\OvVBfn)VA"q:qs!h5@bW-3ҳ6lsG!ZC%?**msrYO)#k?創*gLKcbH8ʂ6f f,JPۼ~ ;&oi ,c12SfjzIEV_}IF)I@ϋo7;o~!;sҍKͮf`ww4F [5?=ˬrzŽ $_3OnxC_/`}: Hp=''"XZU[L۞;~\״=p";Gy6=p\]\\/;s:zgt@׉ f5K?M3@6$T7$oԸՊXDBr^Z6x?B|EG73E b~Ӹs3'ߎg%h^Vh|մ^1 Up9:G/ ެMpeM~} !x՚@B+W`zXej ^D#TjZ"Hq' q7V嗚'$F9Џ㜪@(Ul9*82!gQ%hUU͎~zp{,8VYآMQ|Z.q8Y$L9G8 q^VAe)4qC<t { 4@a$}A{DN'Yďl@肄.˜t[Xq܊懕Y /„0ql _($.>"xwH ~hڹMLxɺr- X__jWD'C(F Sٴg)-)8Lr+4H]>\J[)t`.HȝN;n|EB& ^-7ԯR+Wa mR T#P'Cs!U ~oN2Ղ\CP𫃂k ![U !a&|Y=20`Jx0RƇk@j:@p.' .b RK[EfOp"Hja01!C>#01!6[bB3dEdaz(ALH7 >k=oѼj#"5qzoҶX 9$~ثNBxg 7߈m1p@= Bf\wB/ j&A[@E]B@%>; _m'b; u r.O&#I9'M}v2^3⒗a/?E ;͔!t"BZ[ o# ̉e@BCD7-@Trs0m п<xm!⫰7&Bú;=dyljm`+B_nEp/C`{[')'@Ձ>zyKRsK୏A0k_@ alx.؆Flf9 uV *( &B%8>iLM:@+xkcP~6 UqQXdh;',47=|Hhy$I並t~V'dܢ~2Rp0L}L OG*.v| *d> &t] _K Eĝp#~?!1\ʯ<# j `'-JESBZ̈́a*0vT"b&Dv !p@d&/fB_>Hi DAɯ#N(T jVF'+ N ( >t1m+=K͢i(HzE$nF"C/ʌ~m%,܌$$Q#؛l"9D4IdQQM=NuUD%vjQ +E"YF!Zߗ7czzsU`!6iCLt3 GMͅxF?ԲU'+D*gdnf?D?gEW킨 r B~hiP%ON\aR.5O2#Bi8POSNvV" Sk~nn~~U5c%uX6|$V H(5=jd/V W(C3 D`Sa͌s%ֵaeM=VTW%c65ە*0*[s]DI٬>ZVEqJW;;/NCXfƥcCRӵ(SOAFϡ,SK[kOڰL/붺]ئfW i: )suy_ooB>xՂ"DŶoU\ L8INJV2֑4]]@# Y]i] ++ϊ,s:^.fvZłuX Uv vڷԱ9XzF86dfjxv\F';kߙޙ_#RI;J>w+ X: vKOJ.X>;C~0i endstream endobj 135 0 obj <> stream x][WiZ>dgg6,FZ Lzڪg') > |}=;9ISQmj,.+`&@qv4sML7SFt+@<\vGg6vd1N%%a_@}cݮ)i6 wl0l0k:ņcZxvXb1~{k~ؗ)pX([}_<Ӌ6J읁FUM<4-H!ҶT50ձᰑǯ >$I%r~{\]At0Nc>ݔ0h"& GtY<զ;l}Hյl𰺦._] -WTYwnH٪i2]61Uf^ GLU8˓,71.tChYyAZ+{(lNNx~P= )Gw4tLGm!u 00P Mo?G=^/MձW#"4cTJy1LR9@uy9䀂a{͆Q-F)/1F Ҙsv+;]X ZB(S@U-/S0wjPBAAFqNbWT)tȕ7gAb]ἆbS(~%pZ*$Q П;wHe"Rq(ȧHEVcd[ZO\AR B#ЃlG_AV0"A~}}c*SѤ.edAA#?ΆF**f sSD$uw|1&<2b`fS=21e0 1sÿiqn"?ue%{([bAD>uyic& bD$O]v ˖XTA{mଡ଼NMu!5K([&EN{qˈ-s3 sR׸&I e x+e%s/%S݄GC[9\?ruBm-zH#mT!m6T =8W'}˃q ;xXNLj=L]DWʖעn ?YDɡ._y6K/c;2u?;SVP3rL'ņ~vC~IS# YP+&SVlWJNuo>~]ܽŮAp>CT䎎.?syruUۓ&uL#q.3 g.FG$PUv,Of*kT`n\tAGjZ#A(Gw5 ']W0FcjORG pz]S&tw[Dn1G#$Siz> QARCG!:R7,I0Dno`$n| f;x5pSAca!.ԍcf8 -<2nuS%>/5 nb3-ҶOllvnZѤngI:$R5GIS31GPw_Dstj*(fM3PEKWM17guoZꨢ#*US։|{ 1G+S$T'Cz mYLAe3A.dAݮcy35H \P lc]DϮ4f& |LH;-hDlҿXPӸiHkQՂya>4$7r2Q1hp܏XP#{{)iMNLp0f1QS3|!S권m ZVCT 2 _m'c!\hK=y4FЃgx:aNdACE8 OܷXdJ1[YK(uٻ[ HAϵOb5$TTL ,-=,;m5FH?T -:v}kJ(u#(S3%0>˜H|ߟ/dA]\Mgi`“(t0xvH%v\隶3E_SIC2]V-"Y,A/uۃ|\=QI=JvFŤ M C j su}by,^G/>7U3 ߲+#!܄'Mxݟv ֕`FK9*tX1"AZA$`“00q9?[`Lզ_{w%/5$v>(X 6yr~L~=u5B#LhCƸLdLCL(8 >vֽzJ`;`LN~ n3z V Ϭ~TA>3YUqIceٝ{;U۱MQ^`;?xy IعڭLxoYhkΚۙNLj ! 5C1m^?]XiJ L"L&1hb{Fx`c7{0͎=oy!X|_ް/MH8;SaTSlS6s^f endstream endobj 136 0 obj <> stream x]lUgkkۭZgh (~D4!1ݐ !Ԙɀ/ !$jj4“V1-i *ml:ܙ2;;3sϙswgνW߽DWmɳlaq“ ~Qf!'LXIw kRφ(Qs#GTۥYPHGXP,qŚ|?:`tJjh\`zcӐ'm#1Y-y-:f R!1˯ﲤ$: 뺑0*" 2|L $D_s7.BR;p} N̸ )/]E`K+5(g&VVy )$ U>ಶZ.ށSW7p̗A$HfwPv($XFUn7|+\- ~' h:+0zHI EdĈ{99PFAG- ތ]) DYfL4PLV⤳3(`+ RZwáVnx np͘D ]{k0Ml͑2?}0p }cV8gf,y8Wuv!AaZ=\o9iu ͳ׌<deGZR?=< j[SWuM6F[m$νzh#3S2f^op+.}NdmYГsF<Z9I??7P}'gg"к?: c"3:c ,I# :3ٲ~Mv5aq-j?m& Fm+*]K=^ {RC3HrO@QIVIn cԏ;[5PQ@w%D,zHP!V_ї-*CT.J>T@ (״xف*gxr&ԈeҕBg[>t0 ݝ HvPz<%1=aNI~k!ν$SPΦ)Á8m=f"T= ӛ5+eξ»R֡ yMWߔ}Fo< UW&w8΄SFsPfQwi2Jp/`7=KH~TՓ{KwPjH >d EQ endstream endobj 137 0 obj <> stream x]n7}W@i^0 ؖm!h_7 P4I:@?nåVrh3%gg#|^QF3e?>ϖQԗ~Rgg^[Vn?Y՝Z~vvfg~u~~2j~bڨ qe3Y/ekhsTSVo>]?|}7Pj)mSw3֘U1Y]Ne0;74jzR?Թ1~ä m 4W4y {ĸ~f1FdN5~`6cGѶڙ)9xc#蝶5qHFͶJN?~(wk#.T/G-Z0sl.fO"GCa zMH% ""$R*_E]77.bڽຄCw AL3DC潡s BJxh %b>* ՛G̑T2ȴ;6u~QH =vw %6 ?:@ vC sha,?t " cy~|<>  6b_b.P+8UT.gmM G|Jׂʼn^% od*TAmg)~ .A}{Z{.4Ik>z7_%«'LKOƷ`tq 8NfQ}Fm^A Fh>tya~G0(AG(|f ƙG|@qt!vJ Xǘ?s@8h]tj3aAȍ7Rgέ3qhF֛OKs6B(=e:~YVtrei[=WD=%ᖂ<T0U-GƤd蘯A7 b|FcPt.^- QU\ p(\ZDakP 3sբ,<,!']r*0aQ z+:3I&}^+/pG >:тH fh|!L9ɂoѹTߠSs'ێ$|`*:ڱ@C!]$A+uV"G=[ҋ`>ƤQ^,UEyΎWp`'7؁{fE<<EA7rpMAxjV+gnDKD0< H ""|ꀡ4JiCo/[( ;Ox򙰂]gC1N{nFIð + . vlU.5[ė p=h9ރPcb.*e1L|'i,Yd$ߔaA2\@Ğ>P{LIZ%'ayyo1AߢZpUJfD[с"Fa"[,kvBqy( V17N jx0)B&{aQ/ >@S0yL@~Ff,E(KyC|ޮ@*ɍ !Y%|'{#uϭG={!8y9<ÏCŦHռ+\'+.Qk  J*A_U1}-5 VF=]=UYSk^C>F1&zD~5+e>$cVƗyߦ&76Ħm7B> stream xW{OǹVk{ZV[@@EDPD##/7! wxX!I߯M=,fֺN!@ @ pG:_uۖ/LJ;ZpsƈZE+>kD bqrYqd'6"_dŞ !^_RgÝ6JVQ6(ɑ6 Hӥ#~ ʘ5zHR#ڌ9RPzRKdy|"j!c#dcނ}O{2"!gWut_@&z4x"v\`<)qZ+d;xu('wAN˿#5D.χ-*Q{4o##g1{Ur05g`A1_UK1=X(9o$Ɯ[K{c]-XB7ݙr;=M*gzdݝ #;ɿv ,t|w`,4 Z2zVMwLS\$P'KBMrO.lcNB{i/Jq" <)=*tdpb ra2)ՙΧRLH95IQ=~/R矔&TmRSPzޡF*̘_/?KvpJE+*c:m@v}6Ix:1L/c_3G(sea5^/tJ~4S/^[Q#J~Q1ʏ$5rӝyel,<) qL"I8%2ͷV/[#EY54hi+M*D-Tr>X9 -dWSC/UÙ }qpU~Bw5<荓b?[8cdNwD[O4d?-@3C vxo#|[7\&'!ƄJ&.u>ړ yӒdEm`a䋼RI8q\sݙ.?/a^ץ~ZT3HXB p6|R1_Zs榍e*Vs_\$ I-ЅJgL)=/TiN7X<2!7_16[X/Tl.!*NHPDɥe}qnp4$$lNE*40i$۝~^A`L]?[[~ vLQ6!%iB+?>ˏҔI8Hg1r ڌ`u_ҠI8q 9f5&a 8ekfUQ澸ҬI8E+ޖ:Pᲅ~P澸ҸIڑC|DA澸&lS9#ʄ**hʔ;‚A~Z#('h_52 8A 5h)N$O֢ܴx^w/G#W$U^O،g='F澸&E6b3IbFDHRALbcI5 'h5m(?G^lutٞYKM§Ī*Ijz4|&IBj dIFbb==o _&1I,}}eVxi$T%lɥ6M"8{O4 dI'4e"~o#ni\ A҈Ikv6KPq ToA|)!QDm`' 9шOj5 '@MY䓚LBM_qAY]]7Vby?*3/A OMe?c}q4-A*dB2f]91n&.d[4ܖ֌/+،T#ҳ&l  Ï_]]P96OBhאZڹk9[Ny F[?̮ߎ 6 Sh\7 :p4E+VmfK1BjJ[lނ`u>an&޲@ @ eF endstream endobj 140 0 obj <> stream xWbi]ofz3's9ӡBW453VA9GPHRQ3IUVUwl mSl݀\Z k{?}xn~ӟ?xуO>}/?Q)GU,񏜚k^%{V)_:$5QU}J?}yo~CwCD ~~W~#olW%Y?W?z?o;~7l9)tS̶w4EVuO__}WmU'7pG?_~k)~_#MJ3hx@6E^3?x~`Tx~^ /if~X%.OogQ|MW֏>u#ΟS!r߸LBw=:Ͽ_QPl0KÁ$$Y'RSr8G3}~{Z?߿1͋pG?IGHG6LjT IՌߠ~W.k?UmL$=&P(7H]cd7K,hؚ.aXEkxQa5wPϊ[_,쏘HB3Bߠc~W9R9>?/4.E*oݏMupc?Ooq͢ނckEZUsPDj1 EG I2d@݃&tcIVB\$cߚ~-ky>y'ltYH/YBuHMZr5'6[ o6"a9,#Bc,H4xqk V<0MoͯW+?ǟ}]l]"R\xڸMm@upCsV5-Vp.aJa0Z(B+l'=ٚ$gȐ'ESR+u hXM9x->e~d?I6芈둚)d3~SN%lm,@޻w/|//YWP 06;+>d+578zSw7/oCka|??e~_?ꯅ֥3tNݦ*G 0epa5Gy<ˍ 2^(ilB+l&([AtuCRoi*^)44dvxmm< n̤I҃mk`qYvia5];]C6*.J3[V RS,y! ͇ 6RlhJ/` & q[9(P]Soavis` +ЀZ1?&F izpN4/ I2lpA#4 ݹ 3$߈shc(o~C!՟$G3iotݽ 5uH}sg+|>5Zo!Ɏ"Z[on児 }[&:ϭٺE ݋p}\׈ph- r8( tp]Z#[dXG}?E<DӅZ:H[>-dccКѕCjjlmhYWv4[(OUL.M`n!G hAVɓgl0ߝ/qC1yOyZl=0 ޕ7@MH]c!ַp2QUTD..ى7g cT*o¹<)&ɰn݈Xx)Р_lx;-lJE!kZ%w#[{V%lYf;[ JeaNEא# D$InYL߁sE/[[׈6<,0 1>x/ge1uY f]pkO"b+TQ8I q72\ߌX6Y[GEV]sP;I.Jaʹ躄L=/P=pS;x/;][ r&Dlкi0]tsQt 87pW">X-[m4(ratkG2QMn[{gNgs(؊p8 sN߸ Ehs:dFB+%a/[myyXsAt]&H7R53 7w:x/ln--5xnԡ0"(JLE'5\݅ ~d1`kXk-l-qG-rPsסH0R$bk]'|Z `°TxnHc+Z v>(FA$Wb%]ûA؋x΢:ܫ/yw Km!kƷNH7͋.ZYNN-ƫwCGbO ^߂lx9 6Kh=m]pc+6ߍ` EMEV0ꚍ`ԵTkȅ |Qq2["q 4Օ1AsAل뛂Q {E?}ƫַK,B {uݏ}tEZ:Ѷb lm)Fry`°l2bp6+([sOYQht"dtTZ/`3i/5]Z.ɳVfl b4 7 -HsGf0K,h.Fal2^<r?;ZYt]&zhz8jtU:Jˀ0@3v =lXJEWsݣ]0 o.JUX_l  lJi6Z}@#i öODm/L[.58=hIY3 K(jFLżໍkpCR*jmeWV9}!MսU>标`sO}QڵMSUAjD\f3.f$]# żnEIis0n_ewdbBC&5A`![ۆ_}WEV*̤峛>Mmq8H4NxmgUl/|BSl#sDW82D$!z˂,!M lm͛_|U|{{#TMm !)zֺf+㡼az^pk7zL6J[O82nJ"}#Q M5qRi\pGOj`k V]g̱҃i򾤩ܸ  ưn`+b7z%"j|Oc5m HH3^|Cy>mW6/f @h+ K rQ/ `Zl=a z!Yt߂ȊVG2^lPCkDWqgUU4N$X,Zŵ!7|![k,No=nZ Gwk4:嫨S觟P6rBk)@P6ãH]cA&A„"XEZif/U7U7Y'ۧ%V eKp8'hjD4(\UP ts8Z)rŭVl#j#=E[ȀgLW._V$[SYY8BR?`by:/Pm`yRbJQ%E#({`+5t4t/o'VVXłr#r?OkE荽{D"?m@345e Fhe%VD06fvHac o1^%SZמ~_EiUb`\)8R- )>cFH`J4ɭnXʅ o+9q85_ϊls w @}RT @=4U=/$Sx"=xX*F5@4JitpsxYh8O'Ywpi~}&6-]BȦ.D\54t "cИ ij+zffz?vb/K݆n}M&u0p8V]EHCsA͇ݷTp&c$I2/V9Ž7؛ŵpy`a2Z՛"$Hq.9MU*>Ttu,Y| AClta Hk'Mw 8D-!GR\K`bj60e&ݻG-TtPx_agW"!u Y7ij_WR*^N '撄1j dIܫ<#Yx ,f#\;0+9)JQu6yS54$+*bHUJ9G7VJ$i_郀&lAՐl,ו_{S$Su)Muig2i"VbMe+%[y=HwǸ&T+aЫjaXz9naU(*}Uuщ8$zsMl< 7lvILd$y@d~.d`=pXUU>NUG=3VJ$i_/C EIXhtrxڑg.EF"z'Z\5GUCTNd093/J#g_,š3뇄aa[F>ҊKo{nMkzbҝͪNT2.}xoI҅ir&G'ldd5> na'YB-ȱS$;kݗ  [)Ҥc5|0`yKn܆ڽBo0Rُt FF/稪!݉X\&~9])V kc[彛_W,D`0!.r#csI>?U)>xy~뱕R M0Ȱa/q!DWg5U<UsէG2VJ8G@fa ȁXu+/BG^E '*j,?Ůb+Y7.I{s*u\&us7}9DPak) 1f|ڇl}$[)}m \Ћ!M aW8ҝr"aJa#XD󫫗v;a+P\ !0k8a;t򹭉z#agWu%Dzd0vR:o]AKZ('S~=-u3q!<>뛻S& .weSOzJ9O q C,a u aW8lϳtg__IP@ȺQ0>LHrf;iyUPl bo\bx$"aAߘ|7^9{KZBN$㪉|_(`+e"g\7;M=3968ð:s@9̆ t` 8>pT2.}I.R IG6IeCB+(#.4 MZe)wU{M 0\UALtB+TQQbh%e*%ҨDZ&5ޭjgb7AUʀ?J $=k[68e",5DмD%S `k lYf28MwgNU),[)|1r2-R?q@^@ONh=FU;IIҽFU)˭7V9¶iX I$ِJouO'V.VGLhHHUt[ӃGPeRJrXp k7KUʇl}XlMs؛l$fVE!#?ߵFh,zlKs@ML &.8[)|fLkq-&ܮ]smC~zCRk_`B9!$IvkLXVa2i*^5 Kd4ɖl)ƒURr2O hFWf[(UTUZGA=pd@rxRl}G?ZnHR"/ҋC"D7߼~Ꚑ?.ut,[>*&嶤@-@* R"I^{=eNېe ԨџkDz%^).M Oñڭ7nqXأ w6ȢCpIUU z7 Pc[ HxE9 FXrNoUƥ?+|]z!sl[dfosm#2ffC.5d#u83i(U'q=nEƘɖqU5磳}55ݡ[v~ŗa|ڵjw6]W~Z:F!hì:P7FM w\1[ۅ)lh}')~lnlz+Z 6AT,AH$W?k9n[}vgy^ѭҠcǼު[m56M%2LmB%aZ iz8I]lZ4ĘoQT4ki|MtܱwJIjMZ Xt7Upȉ[kƢ zkteH eVh]NPsԪJUU0ޭOCl€Zhiqy_oV@U7qD gak$c0Oq}$HDRsMW 8K}vQRqn"&TkXI#7J3ú@ QeL;HmV c5G_(*K)Owޡe+UFId82*Tm66FSEp4 GFj2ZIW^CGl`nNwrFP+GrG%,UUhu - pI67ZX Tͣ7qX41f!oA֏?{PlwWr#lMYretuM /-$=6/ڇQ H`(&TDƒ-ݢKz=0,EYRaSn/khF]#=pmz)12hc) d?  QŨ$C4o)AT(kUDFXZWQ 8bYħw8ܧF{h;X1f>dEַaI!0đ̭-Um .$C h滵MƧHP@/ooq[%KpHTEnk.q&9+ngRhn3gU-2!Iҿy=U8l7p7ö kUzuMڦmBNG1iݛMjkûdmV֜XR-#B9Ηa[S v>?I#$s&n0P;>wK_LmJ91Jq/ 7Il[ %6f]c=>D Dn|frr"&xR%EYd|FvCӀߩbi7[F(46MS*'[4VfZTAu"hd P/&ݻAU87Rc^.>3U)C92#QEX ʡqs򇯼;(vo:|UD\ ΗQ5E[ܷS)XO+VQlrM_ftMڻ!H>} +,UR+ūX`@Vl#l~u¹50.ul/Ҷ?X2]A,LH!:9M&! ٽ|[`sISsJ*e(Os[5O']#:x3^Fh8ӇTDjK#80KBp%w0)p)*[)P (_SMF ;xY;v͆Va֕ͅīج .*SӑWj{[n[)VwS㋻CִbvSDÉH<>"]Ah`iCfb)l.\R.aRb+juT<mJk74 CW z#L(-eX$>8VrQ&O6[)p' 6m"f"u躶sb]RLMħ:*V3LC*e mRDcl/pR?86rϴ[z!e[|n@<ź^t tlo",Z|b0>D2U)<[)5N%Zޙ6K!5:gB++ i[SF9M>jY'D|&+}MRj2ZtX!I8q5gJ$2o.]n ֕ޢPTc5SԀ& |pb_G^$lHV'm(Mk@tZ{ht`.7j% FLe..WULːl&f;BG#} m͆ 9Nr[lYCk)cz5[)d69lMwS7AD6_.MH 5GibhpWp:ʭVa2״f7vWDž0k]sLJ׾ @t"EUʇ2 RY5:ö F#aAt_!#iha#={xmi+簰f[oHw~ZaU>3 DvX˺?F/aZgc!=1m$ 뚗4 ’$W&, <>*f9$Zl%I]]ɬ袓k cu9qxU;VJö~ٵqvpuZ@#IkJa/ C[|+CsX*&[)g3ÖAӚ޹38R- _cxBR@*ؒz5l % Js3@`bK_\W+]/ڡM;8I4!+^Rl4g,i^= " >x70]H&,+wxܖZB=$o;[L2[);*Ԛ,otYuIN) FZ:b G)|t>IrylcS(>>"y^/Yp"UM_Cȋ8[)g7%޿K aA-h^ b$a.8BӸʕ 0 "zQ*fy[1!7e:9 /yn#]PQ;D(MΧ ޴rD #Ir>°|:(ٗG\w)b?HD!PuWU)ٚ޿pn ꥝>Z>p pHX[䨪!TdԷN.6٣Ren6$IViMHZ'P@t=rnt;zb 69NrgX&HgO.o{1 Oag Ie"⌼3kcX̛"nQ2[/2ǦĒ1.=d#l6>7|om}aq-5I.ەU]JtUåmr\w)ŠU΃It눰t6m8]_qбA'>\[T|ևe^J`SZ;0E 5;Qt,Cd4=rTc v=oelKdt)|{q*i]_ER-36ŷT&x|et&bD7Ŏ;'|K;3 YӪ,aQ] :$ңB!BoGZ1/#Ir.FUʀlM=mΤ/H Mقŕ{%,tAê3UĹx|1SbuwBѩ_U: NCǼFus5Dy|͎ZCLcJ+}Ư]fe]#L.Þ?CV"PH7M4vD'ݱJ|$N|dPa="q O6,Uh>2@VKi*5go쐰Z&zPQu~'dI ga">p`xg?R +##8xt!UYl=CD̚b؁XH6>>5Kdh0eRV>ziyJC֖y_&lCM`'Q}i;ڸI YL.y*.Y-\x>dqW^4Mƃ>aD ̅T]NXt)K_(bpG~aDD2P08u- ӪA5*XG>d2[iR9-oL̿Zw zf[@/Wcx( 3,wHiJ-#_N a"kX[A}T$q(YՓZ>V9^\HeKQuiYl]Ӂ=kkȖQw{DaU0p(GVrTuţ`eM,nlUfMH+45S 9#gnGsYu>x| _Ll*U)Nw(Rnm'y62[OHޕ7:k-i(vGҙ@ 8Inʚ˫֛ҹ!g:MF+)-L8* ;5l}clm6xyMXl}I7!*$T|v;[LͫCZ3aLBQ7*~oJeG]y=LXQӟPToNL;qFQJQ1“9J2[oBP$.C[qFBehQaXoQ=^?/*MV ~o*%(_ IzަFUh7 3yWgڅ2\+ijIhؘ SewjДկ6OEk'֩$ԧƕ)JVyIm,cxxWLmTggReҮf.]?Mi9ޡ]U9YR%Za"X֎acȰ%:bΤ}'|HU9^V(8Iz^XE965ĄLج|563MN-p873ܖаQEaHtR?$,.VcڨjFzTu02[iԴ{O6[t5ԧXRmﱥhK3 GucXćqMnyx~@NL&8R+ǔu9c!XL- -hZ΄ щa.N'ٚ{cm-3g^ ¥>Cgynzf:~b3I;t*ŭ[i^9-R9Rn%H2  [Ѡݟ9≠CZk.6ŻvC*CJ5֩Mk18^庆b'ױ͊ 0|!g!}y6;V$?/b/[3j3O!Y\90Fݺ9e49߿c..:a'q=FzPזzPm}}ZA]vU"X ^nam2Y-1i jwl㞃_׫Diml~ߔX^sѲP#{'va~O/љtKUGk!"eq6e^RUW$ Ϊ9[RvEzv,m޻wq֡ޓ5aGk f>0}72[*$[?/cm;J6U<$i DǖEC si_Y'R^{ٚy]IKmr1- =Z)Z6n:<uBȐ j93|I6I|S l^Q3S+/$֌±q.NNV {:!N$b:- 뉦M1] ,l=_٬-nNҗr(2s㛋WI}ne!XR;!a5rCHw{zndMWKQ՟$S_0 k+H\ڎv6LKzJBbۘ :6έEE5,X%}Mcc\蚓'vDbM3MXq2[ϑG.xa*7.IUpALxl{NɮEV8k.._j#c$}%;X+bQ=U)kWkTqɅVJwHs 4tɝ8M(qDsİl\V6퉅3WDBt< ξs{:F$lݼ9 Qҟ mċûN͆C;#W1I.P-<$]z_f;<ˣ"l$,_]^(K\=o(nR=,UsUH+BB/gL>O>t$Inal.[M1%r-UeǞN2fWf&O$wi\\]QY{JV}5si=9Înt9Gi\9Q)nw1VlUMc`ؚΟX RV) YW|u/{AG,|[Wت.::QؗnMv++ ִV+}\t=s;^+&a;N.%[߿clz_(F왙mTlZUef'6\'rvr!Xh2ұ ZcdVuw:KԾFU1+̎֩. )2"9' 6zklVA>UZc %\yjZIҗF]e=;¿'Rb#ʸ>`|nAuڻ- [ZqU x&<%C+%qgqqPK,__o3,!ǽZbBOhт>[U59b Y:ˡ[R_f%mH5O&wVJ G[S<^l[DUژڴj^_Gl/ZYucgВQ9qIiذVB+e^1\,aɤ a[? lf,3k>TlZs(7SnC+}]]s+CBaڧQmTfL w3C>py]@7U7P'K~*h,Az64> EC*U>CzȲ!u\*--հaCM5>]5\Tϋ)N*vՐ%&v .۰֩OuV峙ncJ% T5 ޗ櫵mngn &EלsĥƄj*=%[nak.٭[$GgkWݐ6L'xl5D6I/d8 ch; udT%zkjwr2 u7ϔZZ)uB:*O]<8çdLxkPʑO'SxaC*U)[giZgi=Oss-0a1-*A5꛹QR dSeoĚbQ:D@։ĕ>6IL6&V'X$=4cfuT5G]vGU ߠ.#ӱkV FUCCt=8n ]ca㭥jƕ ~#%8R?Njx6yTO0sˎ˲&@tpVc2ZehݸJ]OH-E*q"Z?NLUWYy9}9sTQi{q_ж֞^|fdeSQ QP }RI - RK6aߛeuH%U>AJսz߭VyWVɴB {ֵi |g b#KWJץEck`{Kj{V5vCM,VҊG[uң<:9NY?O@tDcKTXZcfRI^+(JLZˊ0E oj*@ΰQptfsmgEfl6JEg֑^Tbr%&+de)]FQ*gU$YlbB9RKrֻm-#/iUZS7F#oɺR1@X4V.)1I1*hȷ^il؂Jś圳E3g/%xDFcZ-v,YQ`$3$ ZWu V(Ǭwj%#7*<#jsXn-^d7WcgkNRI Qpd%*ݴ6?R3^=s+FE>eFd 1*yJaV`7 &V3q{yƱWQ6x57:8vJKE@"L^ʋ0I#==`(U)r#*zTy [+ghG\bLDehzTd4= mƉNS6SF[/;MD*X#ZzּRN`{QS)K1QzB8|OyA:a{RC^QW$J77b Fzda5L37*T XWS#ֵKֻZ ^R1SVj*RuE4i6؞T{6pY1byrBd8k&aeɴ€U#EZJ~pDp(]E K/8lj}DIZw c\ėV5Mv;\V e1w Y~/T^nϬf5Nb[Aeku״nLٲMG_9o=!VAoKܺgkE*tD KL3/0 2=,\ʢRƽf4H/sƔb! TĐN8FiNkZ^ p(Ѱ]Z2z¡p.q#BaiA?0VhrGU"?05S]mVͺI2ȧ B3b@OMV۷]eDAXu4ؐ$̋2]^^W[C Ϸzo7/ TfMG F^K [T`+֛QFҌ*r\R^Q=ћXw#Ð MbzH}S-F2^UPVcb4l={Vu' 39*0?֞gFvL+}YW }YauDumt'0|8^& cխ3kn<֛VbZ q{u<6z8෻gb*熗Xͪt'VR_>T+a~uI#1]*n Wi[OF.`pV 3֣+MrCc'/[+f &ƫ:fT4J5S=V_Hl4EԺ.acmN,V(c)>xU*,KE !"2W-*G]Frr~Phr N7l[& t/u8*VS0&ڋXp1s($ЪL=c`h2ت^(izd;}-R#.4cUڋ' X60;E7 i Kȯ#V(iJװÎK Ya"U8Z0?yA+oHnF,upUagF=z\a &:1[I^ /<6Oh0U~sr#/'Tt{fr 4CmuzDٵqX^U׻P:]h9UiUpIY¾i%mP}߬+tzs#,Wo=תWvPJ'uV+"ݯ B-C5a^&dܼZNϸ@B',>|ml%I{9~F}#xeI?JֶfMXL+U,EwK0a֕.aۜ>#nn :ۜk[I{j_(l.׍0 7jܩE ,jg#wlv/y/)j׵Hص{X*\?[P}Mj{u.m XwFZHVmu4p3ax9YdB} =wDrCG8Y$0>}`9Uaͥ me-ZW֕ `.SG]k-[I_< 5}O@UFa?CӚrXh+%[Gnr~+GgnqY =]RrΣun\1k%u} &^7 a,r5րuE$ ւA׿ krCtgMlm'IzN'yU4[i8X5bU$I`'>[W*st⊭R86_kz*WjqxM+@(/fiv\7HժUs(O ִhe(Fд°f4|ڽd3#=c ,`뾃E`\uEKQFcDVXNZWfX[W*(jNQ2]og+I@DXTrtek.`][m.+axUap Ls+dFz`\oYNU( դ 50uM֕۵oU.zuԫ'l{#O8@Χ$Iv/U]:iiV)0% R~K\;& 5kd+H"#J+KWFQ6痿xCXI$fٹb5@U7 xU1SLڵrTFXt60,z0 ֺxj]){v\%y¿\^xTX:a*kx|H!~l y`rTx֕zX&a֊¦gWt"0ҊvEI[A׋auH2r>xCX\\Ngb<:[) |t=[ .h]RT#Z(KxX_M>gZhx`L"22ݴ&8K6NvgtwD֕ׄEENmOZ<~AxE= Q?)SbeޓBi ۟:n8/RqzB9 Rq`kbZ=Vٵr46MץrlZaftiF ȺRZ9/!-4MэFUa4O,UamT5<u a 1:?Ibʚg[˅tz5GZ%#nZ+--5-4 SQq%u]*Wvs$ -#ϰiAR iAYW-iZ%HӮI}Iߑٚ,R1p3-sCTclzCGgBKT`WDM6h !TDVehZIP#_*7-6cj$+[֕ U~;tzG=% }OmmNSTEýiѪAxYWJ%(άa]!yO]Rg`h*IM1՘%[[&xMMe`]Lhʩs'vG{^R2-T/bV)w^\֕@wJu ڮ#Vu\yWT) [>VV+]:P+ag̮۱Äv}CVtGUi~ARq%!#BWP[:ĺR}v-',R:p/=&ȯR%jZK+l8nt{/̜;v4RT#42K#ZӜ3=Z3T\+41}owBBPfn彾h4d R_˄ẫ|ea{y.ʯz|K)ԙΔ:8"vEDSwF#m=O2ԫ|F*p+ UZ/qޡ+! VϏ%2aꤸVMPrQXK5WԌB^̺ NԙoY5nM!id&JGz ɾ3`q^Dl8-;z^U+4 Q`-~VtB#A՗PCa;bO|yV0>ۭZؕ `HDjd(ymfs\(vOu=8Rw_}]/)D%J,eSHrdS%%Ab1&bἔ qZvƍQ֦t^ii |V NEx ]Xdk秓??5l#~5j{D#5UNq^VlŅy!o?Q^qI |LB,FbT"A%{b+iٗs 9֔J wg3 e[VE8%~ΜltgEMbEtb^4hI:]61q^\lŅsXJg9^hW%JT0 :"e2T*l/漸 qZzZ+kuܽC/9/h3̾nrZ H[N~q6jڢiP/V_r!bԲNjWG҇agᆛb+.\ʯ_b=Vu2&-BAp](`LP(L,VU΋e_]5lHFo!o:jrp0c+T4tPTNiN tb)Uk%CFU't ᾸX wV~Xb|}_6EĤ`qƞ`ff:Wa;EQV.9C+Cp~MG`~aʛ5^J0 EǵwՄX8_Ml}`$IJyȕ+W_*Lak㼸X qZ`atgs f@7NkSq E6VrFzHcKegD[)lZчS[l%I2=3`k+N I+$IJ^4V^(W-TX,[ "TR+8Xn8._vq^h8-ƽh`NZRA=7LR1 0V$͵SuᢦIE !)xe)_¨]SSJ` 12T qبz IurgI 3v@zc7ZwoVvzVkpU&S c%BSSS^yB 0*|je*DŽ8flG$5\z;YITIo[Ϟ1 ַ7M"W2%j{`(l\ iU`B}n ,8,vzAY=]7Z_3),p$X=ݠkMebO~+}ʋԪl!CPў_yO8TlJPͥV?V"U>j%~E2&LC T1^? l# [)Ceo8sN VŸL+`m>븜%h |}Uk$`MS$J4W몑b)ߢnx37gX*ȩ~RǷG2}kl=ޫkj)!)&JP]p.텅VW:'X S*HZL07dgh#y$ ֺ kclUL]r9%ł!96lm]i9UixsM+)m*zA3m OU;m#I҃>gh#-IfP+̷Bek״rj%^lkAU K("uey.0[i:mOIdh#-$]OۛtB֕#x`٪j^\,XQa}X׾Q΋t!F9b:9X6y1M52^NFWl}$I1V(O6hi]f|+\B\)# Vð}n^`/Pq^'cr FN`@!V($:ڞ D!< |@Z2}}yL#ty640?y5{pVEFc$kez U;cIijl'IñVkeB\ Lk)qҝU-=V jK8/۵@ M+]K.D* >޺hZMm=O7P$iiy*Dǡ?o-mήdUTF[I'm!ZW0ޚ+0")("XMeT :`Z1~Rrv/Pkp^k w B_K9^{A:Tk?*弄B|7N!)(i6 "ul^/M O1,L+Tl~UP;lxkit{svD^$Ib!#@8煼[C̡KUiZa4uiNke|Ve#5d-zL+TK8i* ʺ`9q^FՏFXz'_0eC}MPl+FC3UieN֕qu(;ʃqZ |>a5 l=Y޳ FZwh 6iӵJ[Kh5bZQWzl ֎7P$I:0 <ohxF,Ud3 yn]VԁHP 3+7iX4SZ7 ajCR7Wtp#V(7)oEU B^*P' ѶYi[ˑ*kaegVZUnH XWfLoFb!ѲtpØV(${ZWV7녋oWxh)͓,U`$́)+be_lIZ)ٴ0#rL@z9oϙ|Mr2c/$Y;j1q^`k~ŭhg+4qWH_{Q5u\z_PW936:ݥQk2OJlkuL+xK,+ؗa!^,+i| gZ׺c~44ձd>;EdkȮ7 쭸a r\+rJ#Kb=`MrjÞd]RSX-Tx|^yQ,LoV'5Ȓ!N+'[k/9jDvD6i;6Zv2Y=!0ҴBI[o녋ź"mWz;c{+lD +& ҺӲsFUbȰ1& %`QU(ٚOm܍nZ,ϭV>kul-W!!^o?Z J x.+nڸ$ gw ü[cFIQ3?Vfie8Oz];ű_m uwV/ݿM+T_s뵘xg]/\r38sol\,0se#L.кe[?䇾>"(|Z33zFq]QbG??|WlzH5n.]૯Ӷmg|%qkgES97|ckui,n  D<;vp<3uHSXBcẊ~#Vz#O[zFy*GYfϱcnEx?]V88#zߩYY!b/O~qJQaJ;~Pq]Ӊ_5/j+伎tqZ6\7Ͽ#?p1wN*b*tپ&}:v%:CG,Z}%~ϒ ]|oݍb}_>IQ&1׷pU<=)V+y៊?pOٽ7!a'E;%$ܳO<8 *ϭ䀟Hi|~Wl~.)z#ɇ8~S?[f\T dSd˪թ8` xi?' ;wq]ӎ;'N:R45o"%mNP=@%GVYS?Shxc'CØbbQI6Nh}.EzW{|z4ld0+  _x֚մfE*K-E.ء+W׾jRq ) x ErPjC&iF] TT9ȇAxwL*+b)(Pj].s)b)_۶mwA}׮];:x'D"ZK&'''{YrjkbbΝ;h'`bL1QVm۶-"(99vXӑWNUjΝ;^+!!aljuSsci Xhj 6[lΝIII v키Dzqa޽˵?;vHLLL#c6{wSuM6|۶m=HsH$Z!Q'/ \K{VwOoJ%[uV7xp^mdJRRRbb"U(8T2ݻ>ƍ+̗xL rQxɦM0 w9uT\\=iW@1ˤۇ[ X#Dz[) Sn ( L/B9xL zg..͛7oٲRQ`"ߏ?xϞ=۶mesHJJ3a- u'1.i?^@tS'huvx˖-7oLxl{I`ꮠazƷ22h3l78Hx{?Qw<})ԃu ^,lީ ٚEhŀ۷oOJJڳgݻWVFg |i)<c0b h^8FbZY$\m۶i&Dٶm֭[aZŸҟ֭[azJ+1T.q~ fN||<noy>~%'jBz`g+|,1))ilg΄jD$߿N\Eo\mvSvDŌ26]'$[nj7oLӟD=ɘEOr(pӏl8$~*/T1b }t YWq^Fs2[n-®oTSSbĭEZճ>0;v젺K>CBϢ|FS7V78b5ZyrHͿM҂88(!?%le$0iߧO#ΓQ{S)4s9 ?4l_lڴ#V8\ɧ~Jvֱ2[/5) ֚J5NctPJLrF>ݗxQ/Ê2<] lDѫc_IEO8 J%06ٺu͛Do(}В}TQ- d$gpk ;c{H֎ (sz!l]4؇5b:p!>#͘39OuuAEO*Fw u9Q}K&÷s\-FdLSpu, %xIRRҮ]0HN"d+ьS ^dr.VF/$\!D^ [a)}*rGJ`5>G>/ꁑlc+WwB LOgq̄yBO;÷ܹ YηRbd:11q׮]=邽@?5˱&1XR>sO?rjjsF1@O^ Ԋ۷CCm 9<}pkjÊn'хdC%c /ճu9o͛7Üꔠg {Zʝ%xlMNNf+cO%!} ~j'-LkPp0j~Mi58f34$%~|$ U E/yXCISz} k)Gs; z"Qbpa q+ [#,|$`ݻw3%Gr[CK Sb|le8hzR1'''3x*e[ Kc>X~^K(X%m6jSz[2உ(Q{JE-'}ۓw ~4c)I.6@48g16KG~bZi3UzUR+|gmXӠuOѻ?Ot(YrǕ­ඈjmݛ=1tczzw6oL= n sX0V,JNN裏,G+c6h Us\[4?{ endstream endobj 141 0 obj <> stream x}w| $@Q:HUAPs-H`Q$W{/ * (^EA  l;{gdgw99}~> ;yg9-/d![l+81mǡ3Ӳr󲲲efLKK绳.:tr8pD iW"|ڥ W2r7܆~0jXjX~k> iia9aIGkدO:{!%-̰.gœ9ոPJ":|5^`#PxYB1˰^uN1nn9Nǰ>]N!8ܽurs7H~ ؄eEބvY rtVS9q-|PQHG=a'c8oH\A%V؈R0EsEl0 Eqt)$sL(aޜCq8Α {M^&9WP)0V`N\|GYPx2Yb*j|R}vA}fϋSi9QH\lG m˹š C94*K??;a92͑nWq5함 ѹ{Ϲ 8M(؁Ճ9f7J@sUqd |ΑI8M ^D&G9r9(ѹ հsrH]Z=xTh pN;Wm.hb7E$r=NVޕas9eD`7^("13~[kqϹ'aTΡnFa GK%Qd pN^`o4&)I#WGVZ=ЋVBL#k;iw z9>:, &P.)壗a8%9:xCMજ0d!nrR>Nȇ(AuIΑ!xJ=ia-E42 KdLp>܏ `!VQQ˘RkR8wN69N~ J"Vp_ta݅-9D.%(j1 hy$>U=*5$ y{8Gh7 R䊞 5aq>١{ٳW *@a圸-m#PT`;aD(3#gƷs[$:>sSb !SsuoEMJ8Gx˒ `En&9!4s?+8;"tR$sN0d[vsRDblW+ZxmE圄xCF|.0s?':m{%& />Obe [!ѭb8 8T#g;9܎*JBo(e-Z]+9vt9 n') F !dE ז{ OHeG9#8.I9)IrsUR֎ꬁskY˧#7 n&~%CJ۳f_stv\FbEWŶJ!+Z[n!rt9RLBMRh /9랠jⴧ!S~q!4rtׄ\ԫW5I('v u<5Qr8򾲯5:\wC8]ο8)0s@5Yxj $naYl҆: s$Ќ JD9X+êXoh9I+հF}y.mGXu0]Hqj-0Y|ׄυX:XpNu;u3*}@9'P9K(g=99 {nqKYr fh,qˢK,Yr^ 3Ksi[O֨U֜"̣Ղ ×b\r83Zu C5-A?C 8GǑk貱#GgC9Pu Rë na@$!'d1Pa22.)9dWKG;W&$)yr1Oùˠ_Pb sr[oZo pܣ)j.EOb +hcvvsMъ8P#,A}775قsqov-OK Q60W)XMsgY8Gwe 3!z6ؤU鰏^^渏*~7V⑜«\' l#xq[ֲL]NU&!6ܶi"Eΐ^tQ攣[h' 3i'z_dQ 7up}KkMW:cJK`],4ctApQ-]9a'ϳ,5TYhcNѾÍe7qt9L :'qq4T6y v7]p9lufè0S׻-Ás*]O&Z)\HXǬn"6(F1Fѭg6S7Y2aoי\'ʹn<|V7QrE!lJ3FMϸe.a.'.bg56R4{ZN87@O2mlQ`Гj@g fgk=7n- ہXw=̿E9 gx׻r[Myk9ZSXi_k\Yk;Gˉ9+d1 b}`McIh9dZa&-PmNi57a:3m T#up#klrDj}`ihd`cy7J9ZK 3ptnλ<^szm3q/qR9b#/JRaJaVFKוV()Mn|Gg$9VVptVn. NG.n0,MMeL 9BN a`T-)"sMGg+9pS"rS.)X1#D ƳܭL!s\Q˟fe s Y)5©lsx 㞋gsT^%=z8073NlF`X;>gf{9p.E^.f eTrP{Fj ͜=kGy<K&sF`ü#G8H!C}'1f~95(|P_+\ sΈu.Q\_)A J[T0+lƕ a '_-ٿ 96a٫~GUBDFR:Յ!{AȞ@ʘ7e38n;עuAE>>"X|Tԭ,?79-#$şӱ__l/ꤢbdt푹]}ed E>>څieY3gC+W~xjc=jH9k%ޯ+8uwĕ(r}9B%j}d?o89AmۻJs[Y#ʱMH^#.6@?S&JsmkFqi5} vrdcDnʖD)sN=Ԭvm*\ԕC Js7|݇iw rGMBB ץ9īx Η;Gsb5 7e jvsNV @3agIS,o;&]Дi9>ao99RB:\Q !yldp]87<ݫ6ưsJއUu['9Wyv{tkZ-vr8753lӪak;9W0*8Nf)m6&'9Wezlg5Ôcgξ7UԂVO@4Jx4Za12flB$Վ\2-nq\YyZg#&:cfOVơT9:p0>p1'\ߎߊn;N#JsK $ u[6B)rÆ?!?=Mq;U_:Jp}pp<ZW9zUxL0J[vNȹh-WtM9L^H_a98ǠFP1#dT,sg()Sz 9/|Gh [ :=>vK0 !RL#(}lMsiUMt̩C3-眲81p6 ] kSuЃ. ĹNS`}uy)sM47e9+$`n:9]n?;Q 9 j=Ȅlڽ|czTXjduW[u6=/QDK_"GW{ ~D=Zg(23(}l12Q:nuU>iag{sG~dc9a&rUHsdW(bsUߋUEq?'D9 _73npM&8MSV};BKllemkʰ/[ksb42Z͖bpu[k%s¹ڮheQ m}w3ޖUr?`\xy Z!{4.!X_H笆(sN#CÚKY [ƙrrWcO?{C6W'✋^IoSP¤hѭ8N$p-YQs:a 0_ ;=.'ߖlFDg97K!LF CC!s[fK{ErkY ;m-""r2oȪahzDE 3e/oۃ"Brdsn${ G9L19V'ar/(1(U@Io>0e6_U.'$; W^wknСF֦3>`8יL}tR)_syj'̡aw7-w9#a,{Td)Yni8Es= pDߎxk݄8μmn`agYr$|L1:l9[`PϹ8mvEݖ\G.2DVwNR6.[5WDs{<:T˹Npˈz8 t_x< ͹nU:LƱl>ꐖ`_rnnb:X^8כ?ּ3,+Súfr{eksS"jlx< 㿑qj2.tЗ.ŹyC8:5i]yZۭTr1 Eԋf')W97`iD$"8㖍 , e؅i\GrYR-q^=ESqnYO+e>iڳ $nj#Ц IP|)$89^ނfV5P#ֹƧV` nĈy8Gvj(wi(!::A?R rQ_8s9 ։xvl98M#}\ٱ)b^?Z(9=|e s24\i*ޚACf;Gʏ{+u0Ε}]$2OlT ;`\PfSw)a ]νaPٵeME0.<6%X2N5zF C25YA=CӡOXS lݏ ָ7Z cXFlJhe%_ C+ `3N) +ܧj^7¾,>Zu/Vi4fnQ_?}Xƹ6ːf2v7Gwp',@#Yec'#ox)=@1 _Ve\nN|]Vʻ$h/ZR-L8'wFLgĉ.| )95X˜> e\*m3(Q.*o;'07Wcj=:N(G [uKh[)u1hQ0VB~z&XH*rVFj\3*O)Ư!Z1QVp*q YJ: nޔ՚r}ګ9˔f*īj(P=wU+W8 "Ʌ'J܏7P1RrNP"eBQ++zЖrYTɊc WH.\zF|h*d5[ħeMhr=d9"s9YMBT>%A@\~$a.}eѱ2k A ,#[) Yڗep-#"^ӬVcT$G\,F ÒepUiW*dO2Efh$eJG#s>u|0,FM9|{mR}]Q%\M8^$p!~V sEMJ5q8I㜄y6{@ee,`%pk/h49$*:l0:șyxt%k }hԞ~N qNZlJCy \xNP$b`㺕w>\A+,>gil \C&v䇍{,i!<:sz VO,ιybkᩜޯ}lM/Cja LڙrlsNnŠhsٜ O]6pK##9' _C|$sԐ?bC^ ѡ9W]lNE.W sNl|s,HD&usT-t#dsNlNՑC UT.s8CvFkނ@aXMl3L`D46ƒvƏ{PaUIt|ݲ9_06D2K7!aHν+JHI2@yC`~<$n9H*\Ǝg̹UaAyhJqtpsqQS"s/`#) 1SVPP7Vn-Ά'QjNy[s-7 Z|":Ka!*3SSW4)ad a΍ȫԜj{@ 7]ä%d ssLӓ9T['E"Wm0scssxx_ۀV0# @ѥG"͹8ut}a*'h)Z%*cVjc5||A\&y؇zUMѰ.hUw]o8OjVpd'8zQ óx[ l=prUV[l!MԬS4է[U+{:u5[*wo\ZMf:I͛Ԫ&'OӽMjq kNjUJA?jt?'ğm}񺢀욾jR5 WQ m"޽}EU۫+bZ4|_Ϟ [1ݒhd5_"qH+$<"##.KRg32+,Ca-Io5F{#] (:uFiTXTJܣD;;I=DKe`ǫ!B9*&z?RB›Ʌ]i~' ۫ƛ|s4?בgmg>$@;4ƹaF l9DutQ}'N:Ze?}qnb:y݁2J\1/eZNe>s!X65hqĵmRǹMD AF=iwʴV+Vmk!TU-ؤOfʹ/9bڴL*=lJcu" NlA8/LLlU9ׇ<x˶1T:x;cW9/*')]VeU9:{y,K)q+V'٪qR6kz嵄$wRl$/n%$hZ1kÄL)0@7ei3lmGI B!y9f|G߳\|VGkdqHb(%eƐ~j(ȗeO MthC'RgrC"9Wo&M9Whs^ȑ(_sy$L%Ӕe~CW';@4\Y`WΊ&?U%箼T˹f|j<'48$~SeŝVfOHg[ X cO:8tʨ(}ZCzΩy;sԎ4-en[M0Ǽϩ95sg;.s*7A'/-KI)'Δ,} CUړ{UUpY9R LY|ۭ.*]]r@M[ X =OS6sևd^qN[Ox]rl͚5kNтKRxW`ʹ=Vq0GsjjU ^!-cp?iy ?i-Ğ$`Q٦V!v> \p65krΑ-9RG?Հypu$:~w3eKO p9-Q;7E *j9seR>YZzs &̀oOH`dƆJ!D=n_fVV+e7Ϲ^L9I=VB¦D^S:S:$ċ*"k@\Tj~ žv%\~/O7@ǹ;-1(5VYr?lƹf:џIzνL^Cp 3SA+8sڜsy\Bquu\bw)r.C=`h%N$>sABwS=u{'|Z]_zP9W@R\Ҟsͽj?L?e C5/Rt$犛K!ssܘ{ ΗTέXFxqNƹߞ\}}ydS=~`{~{9sɎ+qk6V1/qnR}pMFYs>Pf A{f{ ?ދTEp‰loι.»>q@佯qk懞:Ѱ8w?:&ݧ*W)HB@F1Tg *`ܬbp.|4{bwmxw{ _/&V0=5P+2vjKbCÛj&um槭ˉM *54qKej}yS?Qv| L{m ͉j?6du~VJuZ~.u]p*̜ endstream endobj 142 0 obj <> stream x}WO$Zf2 Z֭@23AM{Zk7E y*I: p@ Yp\pQ-xprF f:}ԫWsw߈$])= E mB J)_GLB֡)";zcÅSA̼8"uOFxJ>lwYsZPEb^i{ b[Nؔ%,Re4́K/6]p* qZ3оtfg8 !{j( ؗJh^Y|:* CAYb$)rã.\Pt1H<} (*ܱp3|&Fsf"o5yB $ڑ_dz ;2[;6KS^z6$2g SmN9}.\8xTk6TL.Obo8[cf!A> a>`Hb{ 2 ҏGKI b)/&yO2K8|t^/_9Du/\ԑDӧ_?녃Hy2r TpQ]xt!H!ӯXºRE-l>I"IL DE6B]]x>4ī/pqfSa.:9\\tXa^XFw;GpJ.I͔t͙I}qp08 X.&X gvFmʆ VS,rp L,3IͳB@2!*LO`{TXXz7 DKǐzS[:^yqJKwTx|wv`9 Y< 'Q1I@Y A%&p]*5!1\TJ`wgb-2R3+m(>ӟ`wӯ.{y;oƞCLpӟEb"ͩd2ݓ| 8 1K\Ho.PI5.*4SKIe#8?-ض,@I'c[]G3aȇeDR@'M2&=ڴ-\`7DE(3QEN?_AಡPsI`(~{ӝL8jZM*3ƫ2EqjL )dUW{>n)aO gJ*y&f= ,(,y~O1pr`R=J`rAra.QնJ݈> gZojikXj S*==D63/DD5r!DɀZƊQf!9MA!] P3j$ BN(`pQ_ʮIp b> KֲȂ!f|9EʇAZ 6rE::BL5|4@*o\3 Z~85tQ.xA kmߠ涳0e Ϩ3~M+TuLMB<}}?TT-*l汉_vRiN/Rq(ZtREZ9cGszy\8l"G(~6A#W {@s6޷!3AxAI\TB!6Z:2!~S'LR Q$z G6DN**n}E-~`ckRq#{{^o Qf:jo+'oaMP-2oG :O/l;N(BM<OEeÑ-dyqA1uEue dzeXΘK!lJەfgQ6Yl-{YE)vDbi,<Գl8׼*༄ E5.<+TZZI*VgۛN sB PeOIHn̊`f9eؕ(S@Vݶ0 9At*OJM 64lm- L ! ^4W_Xxp0k;TH[i(FpB)yULӜO;.~5@L25sYcK/n2(lCAdTl}+9.~E19'zC-r(+Ldue 󌕼ů9QWRxد{30egLPs^7Yj 3 8?o+-L)+V=[B8\-BzJ/jGI޺skLy[iעLD̅k$CLBǚ.|c+$@z*dr V1EUeK?#5+P!P}ш3-0xIr>v; 5wa *Y6z1de[_b+=$|Zgw69]0;s|m.nɺ5N]`AZgg=C>`l[3s/TmL]zdd"5o A@Pk9x> :P@$뱎9)|%%IA PAE6G2(Bp`LN EiO0jo[[H>:;}7w8 @QvS{[} fܓyD7 8S^~?+l 9eEo񕩬-J؍]>gxRn+ <۹#.DlO2 ōd3K;{G4I!䣬:,dhn\>Z;R2qG%WhRb `$~ϛ4[뙑B 3À(:xGt4I4aϔQP2La2 W?N޸<et1÷d54AE4Ex@v-S{pج rn;A *U&b*gg= *M&7J'6AB<8Q5VI76H`<ޛsdȩR BMH{~H !C8kѴ. ke7w/ĠAōi:=DSF[IdUJ{&)Plܭ5g"غM{?ɧgh5 [ޔ00Jp-(S4fNR 93CɃ=:O,f`[y RZnn\I$ Y5Sh ̮PB& N|]cȆ4`ЀC;?B9+W̤a7ݞɢ(3lk"?\0ixI,Nt[tQr;ո `u`M5MJHGFK<{PzPUZ1;I CGZ+$|x! |#g+__2qCLDհ9?SK]zbUUwg w&U k).4)^c7GKl=@: o^e"MO3KZJLH GbϚ7npF* D+Y%z{mwRt.al ݾ9|w!P(f ,7<,j)rx$B>/){"ZV^\[AEg=Eb&q#}Է,J3Qi`|2䂁ME?탩%eAI0q%:IADߡ{}s,0Av8Eehg-J ۃuI⡚ ^/ j]sJ Tտxˑ-l ޽[[hh<B: h4}K7ZVO%xhvS3 Sx¾⬭+L]zc], ^ireEg-yA[Z!gsvxJ-.Aa"ΉA@Ce:;PhHLWxLC AֽtS^- ]̾ϰul%IKJ9WSJx]y@lتZخ&m#9 G<dz0 O<N?spy_BzĄ 0y-vE꙱Fn_vVī-@ +"[h)TZȯ=zey&UR  k1ÏwZapv<*` gK%¿qTAdv-U>FRm'>Qp<  AZeC-pk8U-u S*YPh4 >tBk= Q+(dC៊~ۭ{, 5Sj=ՒNPݼS*%I5DgVdă-x'GdCs?I G0L<6-!KF ̵(u:Ys"eAz x8yk"3g9H_Wk,y?hT2'v< \-@j!wSƴx;gv3lغˆ:1RxKTW:}E?o/gUi_YC?Dx}ޱr'a9g cU|I4+^u{;W^ă~kԔtnZe.G5]S:C:̏+1D.B>\yJA[ǁgZUZ]$M4GAnU"ґ5~HAl8N !  uީiB X6%ۯ 0?1!Kwzw QQ9D9;f(3.YLӜC\G}j~P[=[rNN [mEɊ2ˮVJ6lm^(/Q/9Qa+K `&0鸲0~e <X]5 *H`ŔC!zW Ï_45"^m]Ymvsw%+bg p~3+*Ttx~ 3VT^CӫL३Y;Bzr_}qkm{ N\ pٺ6oA%~֞P6 tVuy{y'ɘGT3656ofyJw,P%UO`'C7xi$D[嶲_\=Ry=c"v>gt~@ dgֻ`c`;i0UM+˜Nk/sRϰt>ɣGP#ܓAa|zK?u6C^mM>\$vTsK年т#YAfŝTGoW&7GםU@i$5~-|hwc*}+w^O1ã3R+m[@ l6mSPD=|R,#PO#\Z8%zw:Z[Gt}ӗám+9dV|]Vy < Qvexc.."k쪯upz{(";6x--odK gѮ¡Y>Oι<=+y- Ix0/ ul͟q?XeYT~WSK gTԕ+sW%LܟN#}dx\2 "wIW `1VwZn,F7뽋`BR: +7sz:[E\36NY9kڭhOd!-j,Yﹽӳ0ڳ0|gu[٪lM! J%C5kEek8:. mͯ=5_ E\N",@yv$E;ٰ^w*窅1@vǝk+z=NL\ng V@ލUq{%&YtM44pzwS+l_3Ri EdG,Ni/K gEXa u []ºO%\WW*"avJ93ޗuCqy(.zyN]凴plCw @@vK8lxUb23MBj4g'_jEl&g.;6N FԥJ }#jTd[vrHH1^SXq-jL:].-T X&b AT+!35bJIBUpR {Wڥ!>* 8MdBer@L/a"΍[k}n߈]_:}-UY8r?P(5f!hk1On~}J 7}^D! ='zD<f1C6EܛoH\5p;qvƵ'RuhyC9g@n r ΌOySf~>I qA\M=IХoW#FB%47]8=aU܃t8GEnÅէtcNQ`Mji1@#D|($QD!ȝTeW.EwSW<~T/%ՃMWd˖+z<擥>-.enSOi 1d{ $W(ppU1ț\ꚉvMG~:$=c @,9l#b?pn߿ (ZF<qV6q%/(9 O4.x29N>T]˝e_ӻ-h͒A> (4N 4 7}#1(A縝j f)8- o8}9U![ɗqH,n-ßML=X_ßfB`"~, (~ŐC.EۭX`\O<9! H!c_!=M-e_;*(~-lĐ,*{o(=h| jCmP@-@DT)3$ \fº2J-=><=ޱg֭5J{>0>} ى۳E YX6؈ŃRg4zc9XW@ f^GQg?ԱE6-`y$3Vu[f1C6Y.ws`W rhH6L{1Dzg"}|1mtAN_KuOsm xLx$<Sc GNy&(:B J $W;υl=>`<WƔÑ=kE. Eԑ^/T3=(v'ohaT iV%p֋:{FjIzsme¦xnZm!*" 6"@ڔR; KK/BhV ! 贤EBN_NVrBP Mw[6T_r|N3?^ܧIh QM 8m[IER͊ K&[bbӒzʁE{@r%dx+9F TBV![еr|N3;lݯeTl[ r@&z1_h N_N`C˒l}d;T8F K6|4&1HLQK 1hL@iN_QSADT\$iƹ_h+N -A6%r~8EE="\<+,S0iJRq@@sP /껿H= NC|xhą!lA :%s]$Z!SQnsr -Nj85P++>(foڙ/N [GD..eVU" ֣RMԥxoy&,8<}L>J-k"a)4پ^XКMUd&AOfT`V5}:U]p\EժFH7;Ym#uB /nCf`ό҄HPO`)hhU;D׼ݓ< Y JBk̗f{s D o$G`iU24OOmb̰%ᗡ&H9&HN# X N4ڎ8{I͍l!-iﳙ$ SZT-ز!*1to%xŃmO2U)B!>L҇Ĥ۩ -#d>M>}ëdQUZ0;4NhD'PTFD!V{o)IC1(BeIs OPn(٥{͒fȺD!~U]<,-Ɇ)jIb }V78E<.d>_)4/FTƃ҇kL}xm.x;7 d+vsCF]҂mK\6SU#+a7ώn֔"6GT|rdFJ^uaYUWHgSAZ`z D'm8/-֝x"VRT=yћ*pAT f-L컯o" PU19ioh/liˆIHP/R(y¤«͒My! }/?DK?' &ӤDL r5 6D'YAa)B9R&V4߱w0Cؕ 5} >4*,lZ06:2d1[6Dj"lI&7[</URErRX~ZJ|pL\A&ʬkptdz{$)*,БnZeC1^cUV}IFPDa{v |>Pg!ږ,b2nbdM%f̎H:Mp~]WNO ]~‘-ReVO@Q7߶+˧Zыwn맚>Y*Ko5+;4-0Mptpm\ G 99j&:"tаҢ̛KR6>B̿Z]r5DA2RůwyJ%Rѱ>nv|wvBɊ[?Ahޗ=4՛@ G!I 8=5)x`-.졊m2*m7>u7^fɼ<^2ܾOwg]=3JIT5ۛfx%ȇƠ"֚mAC<YtOJ}*"f|J> }TtҐBy/nqvyFD GaJS-+ب@bN5xΥGO/ dp i0< g#z؆Z \}̥\-'\ԃ_󹘲8}7\y'ZCfow5(CW 8)*cE]R^:PR;~ b*(u8wFS.VW] vD&F^̾Nߑ͒DD%Oqll ˶=,@'DmB#k&_x,*յ w;y:.e̯6xHxgW@2+6) g63 ]>W@ H`^gPsP}yvkT8bOcxOWz#@F!A7YCMC.fsɩq7&o!J D O ַ֧h2uz]h4-.v={BtVͥϏT6ӌ BLӜO9.N{ laTCHc?n*,=[.N(ś3tO߃$l$G^ h*p#˻N 7Y1B3y5Rr)[ n!O2oLEdȋ1\j)Gg0HH&Kz06cC2m$+QN/uߑk|" ixz"t_*Ej~d kH Gǟɣ'xyW9+"REF9Tgve|rfPB!c?"Mh~5C^T#nϾ2&-=N '!ZCxEU{qб횛_6ظU<8?5opN !ɮHk v>w|񌕜. PfSAPeқ>$v$?kیƹxXxxF>iR-vQ7DξLƗ }Rs7>߾kE 34l<89x_F tG."xU0PGcsӟE3ڕ@&QYeۈ%.lpбaE=녃@-1JsvpQ{`l{eT6gdNTl8/ CZBsJ(TTTizq=3"$))湇Œ#Apex LDyh`:l,euX~tyʆaqN?ߚ~i!W{pQeXҢwRߔH}αo0Q͞b29 nDwH^VVT *^\r IMZrKRe T Pt/θ .j )GQXT_EY^K{R1%3gmYʾou! *Ȯ`p <WSsKgUzج'5u~8FQz\ș3A4Gqq!]4E{c|,rCl@(J8f ;_8 n꣋isυ0XZ)CFD e$"1D嗧\ed .n~.B}'b0/eOuXc1لG~ :D:06;y0?GP O$ KJwWNtnQy1ᾷ"$ɔ0jh_S 18ZMcpxxTxE[k{N!(AI,״I0M2vsp:J5`M1R׋1HGmYB| q3LoÔ*.iMmr&b]un94RGJ<)̾5{l tJb+OZ8L>C*!VOMs$BP 1`4nN='{| ԧ%З[ 䝾cR0f[36#H?<R^x 7 A @4T=Q|}je?1l)aC$[7eqhR)u!$tNhB$t6ا1#dDi#Zӣ(47(D^( G-.Nx tNh7)lAʃtԱfsQg(bQ"b㩈1OiegJ(@_ldT08ʧ2!oϷ"9I?ؘ,3!x&y?A(D^7o/;zXQ(ZBBR٭݇6Sp4&xo|ڟd..} b@&iG׋vC~HZ<S+ …4HeW&, >Ј @" ׽o<uSb!&梢1mRyFuQV6Nsְ sv\z/9~.\4 !*(TT-02o)-:_@1 2Yȸ2u3޼%3FE޾iJ,? % ^2|c(ø"mu=x抻pQ)w nfDkgmv1g,&k_ET4bS,iᬇMyiTL 2 x(?r=}&wg9*MĹ, Va~x`d)zVM.f j f'a(v|wv^B..*Qw"m\a>hs%z"ʗAKTnƵK<1fr풁XX?o(4FtG "7zYwCA.f9*L[;nm6BHŅ A* ~s^8//&7n6Ndqr@"ស۩%`7C$]wa!7zi-`b .W… A%#,0H.o^wС.~LJ\QLHtr1&V@/۽ OA*T( .*#>=jS$ w?_X endstream endobj 143 0 obj <> stream xyUǫeDeQlQwdAA`Q}3 b*"0*6 "# ,"K6M/t}$tγt:Iݪ,]Թ.q3d]q6Ѻ]SatMaij ttrnwx5YN,zѷ}Nv;{a@L56l;]_}'iM-~xbɋ 2Ҝs˪?,^o:>Kg=tXߧ6ʪoF&T׎_b<;\ԇ]r/zv*x4_(8gݔǠy9%/v^+bV+nMs_R]7i߹ZruHYasTôǮhrws}%rAOeZw*WQ{h]5?rp{鵴ka :S5}O[c56xᜡۧfm!G}o׶E9ZhQmym;M{}l $z-ܖ̓J'* c4;EX6~OHl*N4Sږ,bk҇gd5GR7kM1e^ҕs)U]g XNfg.MqSpfhq}9~pl:KXlmZԛ`i2CcadN)Ц2.FwH:/qQNGeвq;dG>;cO1]yzyL[EiҰp1@Qa|-pԘ'rr -pIS-}ɂkԭ3g }'/Rw$粍^vP5mFbvoP>eT Pn;o-9<"1"XM7dN,59r-o&r^j%=MnLfPRutS(gIJ_f=F %E )Q Z2FRkOJVu!oߌh v",! C^>B6b΀-Nc`in^G_FrrҵaQLUڐBV<|t_({jIgU4y2 aZik)yUͻH[1)8@ l#+@iLjI}K̂I֊>T;e1ΰ-Ň l&S PAin'j2:?!hMYoQ6Yk2#ZI侽ٗrWO5wg30y#8ui!pmXBg yInk~(yx0reǽl)VRpKK*M#w?Wo=`8ڸ,6(BIOs#r<~Rr ;F\Gwɭ|==:仆k)%BL^P@G.g\{(p^Lq9x/m -.JE>ɛ=[<^9yB*]J{6a  }O 5ލ: G^^ oxO[gp->ޱ%)ɕ+o?b!Ěu獼LE8۔Ql!kb4\xH^a=׋4f6:('};ʏݒch] O{tS.r IfUFj=:TxL^p#ʁ E\>rvVE| ^dy'bוdRy~PٵՒe=]?@8 L84WΈo>S3w ,avԶ8oT\ \"Ȋ0F쑁g:oJВ]Kң W5M['\Ą U&/@A]W )).-+ؠeDQ-%9FIgR ] IGW\WG^qkoD"W:,ći;;z$* ?hI5Jy%u^k)<y['J̲<0߃:N^ Sre|v>9Rr^ZtEN1VeT$Cٌ_‹<^^>s%#qtJg&.ǽHfH<*59m;~pr8q~tW^K$wyk<7 aa\~]QnS²}ҨΉtqFԶ$7 ֊NqX(wAFY^,GL:#r\bw\QdT!8Fsk&2)x.~a>7$ޤKlOֽsty.y $Ӂp# Y2n"d &.H ;;8C|0`[}֦[\"> s Xz3yV+^{ źR縭(U톡n>w"r܅T"cݩp8r T(̨fK )^oD1|gfwu bRf++ Ce*o?8}lͭݰSMrK8-2PF1WNUM ӯJ#)'>Lހ_pfJ/Z9#;##C[Ч+Ḉg=NWQxߤh0yKCTFGm?>K> 0D$37hN]sDN^)* VB/vR7QaU-!4 L>!)AO؀)? 6;/}Bd:6NKD&5? & KW%E\A2olYk$QןR[Y^t"haHKZJs-n KD&ϟR種%05c}IOcê:B; HI^o;r,&#f`9 ׅVA!Yg&ZA$)AP|ZWϰ|Jc)Geú+P;XGr]v$#}T?튔<`G]QAx[N2JTmvs\%CǼv´kmZyʹR+ECݴNwJu`Pb*o4W,o_bK2AjH^QBy[SdOW(ITɄG;%iaiL+JzUu> u{TB9/[X -V &X^`P%"w8 NSx6ETrd ƒz˚E,k1JA]SB_6#cGA2yqjʛ6tk|r.^1vMI$oxX ~Zg߬^lyx;`V+߃ϳЖ:t n}ػ;/mqV(SǿV+(%ׇuQu(xeycz|${F;%SY$)Kn6=/+GTdHܗO(ZwͻP,2 J  4 -,iwCzp:bwxǀD5.pzp-K>$!K*.j6l"$h=+ NTjz%Du+t]ˏxA:`) @EU$.F[m ڶ JxD`N!U(n<^ w "2[-9#B^ 2;.[^^Nm_{6]Q7._eBL@^G駇eR Sw.%t~ޓ![Bu-]y]e62*BQGwhet62}7I^קkF܄? :x_(";#^L5A^lTewp_1rDmg{@tzUqy=^\QjEܬؙ*dWΗa4sTElL^sOql5wã(٤PP6).Sƛo,&pޓX_!uCsn|Ahx;/O]!E;]ݗ{~q33Zt%/T˔UMPͧ7p׷[w岐7,x7/s_MY6$(9+ILD,ՉG+­Q|[Y5`fc{&6?ʺoX8 V'`VZmOͶP=b(fv_m,+ijIUQw[VZDo9LO99/MykK]-gЪ^}Ce9eHSbg>\y:lϰ4v:,2 gBluFZԝQ}> stream xnF{]% l2zI (I_P#G,W:@ k̝;eC1XckzsayQ|UY|̗_~0pZ?taLխ|~qvg?s~~jyfӸhb.{oۢ9̿fW_n庺[o{9_ݬV兹0g8o-Fcѷ8֖͋M~3ֆ͗uQ٪-- qM>1ul8uL2j) ֖3|F2>[Ui^ݚ͇JBf/u_֦ E~>-TˡmcSr%nM~f^k ,%5>AbwZJp<.Maz2Ge;X_8;MB]n[8=u&BIM$Ql ޟ2`?Hckj)akTv1R2MeP4(J엊#xɼm'MёkG$6EGOW pU9 qcL#GZ+Glu3Jfd3AÓ;a wOIpNsjsOAԓ\_KOX(.bI>?0c)'2&[s=IxnHiF9PRE"sD NR,RH\xNzy-NUGuUC=}: Thm}* *3g* yZ2ª*| cƞ3N̴G-Ѓ:ohN>(ڠe@A\"]"dJ1r#3uE͑"3g(9SvGti~0E1P-/39{2ܑ&h'qcx]6BمJD0J#,x ˡ3&Dyk#q_4jg2xh*&yET\=N9@O 9uagO3(8VG89*E#ʬ#E<3 @qzwZ:-zif QFw"15jJHYxĬi~s|=B]F%6BuKO2 M%̓Z\;7A}cHd:ㅘ'\!Ļ[ׂmpd9m }팳m(jqM׺>#\!`SK"+ Lg6D'H%RSv$j"X4LP5b}Y/苪ͧu}Qv #nm-WٯޚG>qm2e2W;+[eӹܟ$t |e\h K붨[qY}Ѷo]<ĶxCQ2ٺh]lTeDy{G.lۨC,l' 9 endstream endobj 153 0 obj <> /StructParent 100014>> endobj 154 0 obj <> /StructParent 100015>> endobj 155 0 obj <> stream x][o7~ׯsyxxvl6I7i _$kfl}ChѪ-Es|Pr^2oטyuPFAշ_W?XgO?H5Nm>|zӟo}~|;eԛ7wolEƇoW?z^~N+DMQQ1$Rs5r~%Ihjɺ?S|堺6ye;Շ~~Wػ7)mTmյ1ƽQ^Ե12jo|nqy? Ln}&?ё!JsdƸW#[M9PxGR;~ʛРr:cH}^Y;}AL)bvhigEԕ&@@R֊y< K%o, t1'ծCH%}Fg%vFSv~=Bw(b@`(n;@<Ьz[% aMW=5ӭnGoVn(m;\3,%{ b>hVC2z9^@R & CmOUy+š;M\%ʺXy 2jW{mU[iw>$r‼;^{;lc >wp =qn< C $tr!!CA=!/qH%p(JV#v5췧H&.]1p#'0,tBxP#273.)N\\tH9r ACAf-O+9xP7!&f>ښ;\U]Ex" 񈈀qaRXYvpACxQ*v:H ʁ-X:T0h;ImBjtZwoDu2L6Ρay Vxfȍ# Ru1FYWG`Wr : [18Ԅ8d0N]UrXĚ &xJEWh&> Pϐp{툍+ $+!6Hޝo:amƃJKw9Y[B&(kl/`a=g_e:\|A*5ݓh~}} #0Mƈs>Vd.&NUm5$N#^ `c:|:oqGԎ0":LMdD߯t/X]͍̄U>:)3< _įгM|*Yq4%6)aXyĉ g#qQ4\Uko\>+y]_oL7qvo[ .ߴ=„̐P'm2VD4H X4,Jyl^7`5~4Tv,wiw B^`sPwG$ f_Ԗ8҃W 9~ڬS6B{_I^;x rI_ ؈ aW3ƈcN!Bc}bƻ,mB8ݶe'FP H@G7 VߢDG1EĘ 'bO%Bo-{Z.K`Fr 7aP]j@pF6T|@eDo)\IA[9ea_^ژIxčc M .E~?9Yaa.yr?fPYBمϰXCNxmG ȯS-xqw2TA_P%_29q f_T*Ygot֙;Ԓ['4ϣn Llu9R~ xs?Rjlʬ]e_vd/l[2:T#)O͛ lsy3(|V->~tK8" P=;`]Wy iN@pڂbQd_~ko,w:eްtycO/2oX] :e^aU_3ILRPw*aY.﷍tO~+x9v"˥_[Ke9 XW]*gX />R\+xқ-f>'9)GZ9m͂ K)u a[r E Ce.f; y#~^#lZwJA&M|f dk z5>f4;Ok_|)L% " {ZOcK~|u (Djo7˭_d+%m5e+lΡq^ZCE܂x8D!.OvG)v'_8ߵXL)Cu =C>p(1#9 q7RPPr#j,V X9tj{33m3GŠmFTC5 kdCzf;DBQ'* @WxMjvi',WG zIފJuy;@@)L5rd^'9 (9a*v` .^e*{YMp(r^@0gd~x=Q7Z9" .V,~r֚ƙ„Q Q )kMt (gM)rJAQN6L%Op *xH$x 9JM㸐%7 9QKX2ÎIyFa!/nA "V"1  Ép"?fU$VNǜ{Q]UI# XXè͸-{"x'_8px7'A @#;5C ش8"WV))sCLR5a̦5Fͧ4ծYaZۿCda֨? a; endstream endobj 157 0 obj <> stream xo7`,ɸ= Y{ _6ᒽxdi:_OMŪb}QYWS;ml*0|i? n~8elx/l̰O_޼䆟y/ח߇ z43}yӫlvˊI-i9(6CfZ]Em~nXK4%n旯kyۯ߿?߇VۻÇÖ^`yfɨhKl>y}?^kˤ9Ak/ab_1!OڨvLw5F7'Zʔc kB#hӠqTSa`'7کce>PEA~yD[V/r9L0Gpžco#W/*N/Ab!Cs ⺘)w0cC mIU-gxgmvz2QcRk+ymTb5ISx̰x~U/hNsiU7?8&#C4 g-!fD)/b``/bN͠]K'̑VM>HW1}W521b40r9GSbr;{{.Dhg ش \/0qFS\_5)TM\^Jʴ7"jq ~ pnW踐n\|tB\|eXEK>sy^9;!Ѱ@]E˸Î$5w8>O ϒSpU7xFȃ_k;V^̜}5֧߸ּ%\2=g/^k;|񝬗V(LBU2"o0;FڹeL1w\%*eKH{Њ\*z+)Yw$I)TuU(VJ(Hݕ3`s"8~: 3[)O"j}0  maQ%,i-Ӵ:HOXc|M^c=y2B/&"˛~D187@*q,T=4c>xwF6T&1D+\.ڴ8T$ڛd y&Zb6!89]aNyH]fQDp |u " %STr\~ ? Tŕj> stream x][o~_$K2N(jv?ழC-9̹Fh5DϐtӮ]E nݧJw~ةwWM?~\__lnn__ot}o77^/RЮn[>Ղ취(}ZJ`ɭjDq^J{nwO۷_?O~|x|R477MϫG(HI1\бI3wcW`Y{`;G0G ?N!LՇ߳03T^ e8XZBOzE -"HQC Qr"DPK B 2Z i\bI~9IJo!@r$y.7F NnR I }#La~I)6CAy͂+h` _ΖpW1+2 hA-[O[tP| -G{rҜFIz Q ,>G=BD{RhWph2Do-"P "i,%P!Q" T!W*6BOR?!Ӏ #UC47Y _T ~qQ#(gEީD /*!I) 7hJ/T!1MF8Kri-8tR('C ": lCPdl )Tl/kG ۦ9:$̤\uB:mH)pc8@B3hݰ+%̐>:5~B"I|6(+Bۅhj$L-GԳ)"G; Mq>(tW'):7SÇX2&H2n9AIC7Yj—3ͶϥAFE)齒V^Hеmck b)H.0w@.@죅5R%+r;&Vz &#F J \ ]eCNF7u(Fu PʄRb-^ +[""X~cuJ3SoiJi7k$NN;I(AMXg *" 4C*V/fkg òF,)2E@t놠28tHTM+5V$pn~THcD{>bCI/jBуi͍\)VFP4Zn9.: i|2$`&A#2@d#+#N#f:`_bt"f^pA_ Om3ꑃhI~?ѮnaH  ҸF)$uֺ(XS \N9bӒ3JZ-6 䄣'hUIE/~UƷ:lTیqƘNQ%}skO2EI#wc,Ŝ$᳔ܜ]!m'E Z=X _55 7ٟKEskK'gfqX0?/WG݊"elW^Hr.ߠL@_A+Ivu[/Ik]4w_SGAMhHK0{ȍXhjx\˼BB9bh`\B1`cDY9|FC󨉳~2YM U~ tO7*8aq3[ "҈Lr,kmU^&Ƀzc - 0 b.=xm1ږs8xa ^oIwa\l SloZ?)\Pgk,7.X&X߸(5Λ B\6'S% r-p<#:r8^Uӊ#D"+eeU/+0NDai:iCچ ]Rbi1\бRٟ@?.-9?]ݸ@]kdL# | cjυU k-ı",})|e9arR~s~=,ͻ%Covovv12F;'v|}Sf'kӼsjoZ6HtYu>{bJQE -܁u74Z0h,Hтg\Ga${lkZvP|{vjxz-;mg$nesF61 endstream endobj 2 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 23 0 R /StructParents 0 /Tabs /S /Parent 160 0 R>> endobj 24 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 29 0 R /StructParents 1 /Tabs /S /Parent 160 0 R>> endobj 30 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Annots [35 0 R 36 0 R 37 0 R] /Contents 38 0 R /StructParents 2 /Tabs /S /Parent 160 0 R>> endobj 39 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Annots [45 0 R] /Contents 46 0 R /StructParents 3 /Tabs /S /Parent 160 0 R>> endobj 47 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Annots [51 0 R 52 0 R 53 0 R 54 0 R 55 0 R 56 0 R 57 0 R] /Contents 58 0 R /StructParents 4 /Tabs /S /Parent 160 0 R>> endobj 59 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 64 0 R /StructParents 5 /Tabs /S /Parent 160 0 R>> endobj 65 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 70 0 R /StructParents 6 /Tabs /S /Parent 160 0 R>> endobj 71 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Annots [73 0 R 74 0 R] /Contents 75 0 R /StructParents 7 /Tabs /S /Parent 160 0 R>> endobj 76 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 79 0 R /StructParents 8 /Tabs /S /Parent 161 0 R>> endobj 80 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 85 0 R /StructParents 9 /Tabs /S /Parent 161 0 R>> endobj 86 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 91 0 R /StructParents 10 /Tabs /S /Parent 161 0 R>> endobj 92 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 94 0 R /StructParents 11 /Tabs /S /Parent 161 0 R>> endobj 95 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 97 0 R /StructParents 12 /Tabs /S /Parent 161 0 R>> endobj 98 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Annots [102 0 R] /Contents 103 0 R /StructParents 13 /Tabs /S /Parent 161 0 R>> endobj 104 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 105 0 R /StructParents 14 /Tabs /S /Parent 161 0 R>> endobj 106 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 117 0 R /StructParents 15 /Tabs /S /Parent 161 0 R>> endobj 118 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 123 0 R /StructParents 16 /Tabs /S /Parent 162 0 R>> endobj 124 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 129 0 R /StructParents 17 /Tabs /S /Parent 162 0 R>> endobj 130 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 137 0 R /StructParents 18 /Tabs /S /Parent 162 0 R>> endobj 138 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 144 0 R /StructParents 19 /Tabs /S /Parent 162 0 R>> endobj 145 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Annots [153 0 R 154 0 R] /Contents 155 0 R /StructParents 20 /Tabs /S /Parent 162 0 R>> endobj 156 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 157 0 R /StructParents 21 /Tabs /S /Parent 162 0 R>> endobj 158 0 obj <> /XObject <> /Font <>>> /MediaBox [0 0 612 792] /Contents 159 0 R /StructParents 22 /Tabs /S /Parent 162 0 R>> endobj 160 0 obj <> endobj 161 0 obj <> endobj 162 0 obj <> endobj 163 0 obj <> endobj 164 0 obj <> endobj 169 0 obj <> endobj 168 0 obj <> endobj 171 0 obj <> endobj 170 0 obj <> endobj 173 0 obj <> endobj 175 0 obj <>>> endobj 176 0 obj <>>> endobj 177 0 obj <>>> endobj 174 0 obj <> endobj 172 0 obj <> endobj 179 0 obj <> endobj 181 0 obj <>>> endobj 180 0 obj <> endobj 178 0 obj <> endobj 183 0 obj <> endobj 185 0 obj <>>> endobj 186 0 obj <>>> endobj 187 0 obj <>>> endobj 188 0 obj <>>> endobj 189 0 obj <>>> endobj 190 0 obj <>>> endobj 191 0 obj <>>> endobj 184 0 obj <> endobj 182 0 obj <> endobj 193 0 obj <> endobj 192 0 obj <> endobj 195 0 obj <> endobj 194 0 obj <> endobj 197 0 obj <> endobj 199 0 obj <>>> endobj 200 0 obj <>>> endobj 198 0 obj <> endobj 196 0 obj <> endobj 202 0 obj <> endobj 201 0 obj <> endobj 204 0 obj <> endobj 203 0 obj <> endobj 206 0 obj <> endobj 205 0 obj <> endobj 208 0 obj <> endobj 207 0 obj <> endobj 210 0 obj <> endobj 209 0 obj <> endobj 212 0 obj <> endobj 214 0 obj <>>> endobj 213 0 obj <> endobj 211 0 obj <> endobj 216 0 obj <> endobj 215 0 obj <> endobj 218 0 obj <> endobj 217 0 obj <> endobj 220 0 obj <> endobj 219 0 obj <> endobj 222 0 obj <> endobj 221 0 obj <> endobj 224 0 obj <> endobj 223 0 obj <> endobj 226 0 obj <> endobj 225 0 obj <> endobj 228 0 obj <> endobj 230 0 obj <>>> endobj 231 0 obj <>>> endobj 229 0 obj <> endobj 227 0 obj <> endobj 233 0 obj <> endobj 232 0 obj <> endobj 235 0 obj <> endobj 234 0 obj <> endobj 167 0 obj <> endobj 166 0 obj <> endobj 236 0 obj [169 0 R] endobj 237 0 obj [171 0 R] endobj 238 0 obj [173 0 R] endobj 239 0 obj [179 0 R] endobj 240 0 obj [183 0 R] endobj 241 0 obj [193 0 R] endobj 242 0 obj [195 0 R] endobj 243 0 obj [197 0 R] endobj 244 0 obj [202 0 R] endobj 245 0 obj [204 0 R] endobj 246 0 obj [206 0 R] endobj 247 0 obj [208 0 R] endobj 248 0 obj [210 0 R] endobj 249 0 obj [212 0 R] endobj 250 0 obj [216 0 R] endobj 251 0 obj [218 0 R] endobj 252 0 obj [220 0 R] endobj 253 0 obj [222 0 R] endobj 254 0 obj [224 0 R] endobj 255 0 obj [226 0 R] endobj 256 0 obj [228 0 R] endobj 257 0 obj [233 0 R] endobj 258 0 obj [235 0 R] endobj 259 0 obj <> endobj 165 0 obj <> endobj 260 0 obj <> /StructTreeRoot 165 0 R /ViewerPreferences <> /Lang (en)>> endobj 261 0 obj <> stream xw tיw[RK$-*jalD'@oAxuĒZ$%!Yb}&c&&-o6c;ެ3ē9gٝs&df79QonUIfnUݪ?wUX0SP:DkЋ1X\X3 LЎ&sXƗl@R맏-&iWĵ+ê2=='\eRu@v`3ZM|+8!bDيB bpgъ"p;>83Jp|dtdl&8N8ppb0yȄLo8~g?M?0gڇ掎fx!!l0lAyEZ%PJqx3%cg?~s'y|0YZ6*R +" Hwq7*r5<[x#t, _%ED6:N"^O5 1 59YyL?Q')_/$8R8ICE q0! o#b0?! P`^BR47s9l606ϛM6)g*~/r9n 73^$hR~J.Pݽ]|/Fss_"6ֵ{|M:|1z.\.euwd.F"wH:,^i@a)XLd$K.+r%&1%?(e?En-+S8_V&0pNSF2I.!D̩\"6S6jHI-)d2䛔i\VM&Oq-ǧxOY%ԉEG8$[Bf6bc:t%](U^\ȥ Ow?w!w!bf۲I98*..(,RRR˕esRJjxfϚO|HWwq?s*N]vD٦NǓoz>T͒}N3}*EͻΑI䁍3<FRS2Iq8]YXD<ŵsqRO&ΈWY7yw&=Oq/s5ν:]s}}w__xMJ6nؐ8]")g&+z6q,JK9e;rt{e볾$Sۮ&6t0[K3[ ѧw ]{jw1_Q1˝s{F6𦦹o6J,hb]J֚VZCJ2ʶvW>w{Hu=i{/wN<\T5z}؅7/ OYmsߙ ɖv%s}_ykkiǹyc`#}ejgԞ) &Ld"b=\rr醲X\e~y!-}޷s=v8PǽY.MUUkrR"7$G5AgTV髚벳|mN qyvi%EL)ᶦG_8Hf{ivwO6cԎ|7 oeCj#hhsZ꩙hQں}Rc4mA:bf(WM.,5xeH` &G&BE?p:Rd7sǬɽ*1p*ծ8J<@$Q t2%a>E$ʊ,{9[1u1\yɅ~_*]WǶ ]հ2$$unsV.hT^Chp(NtE/BqNlE/8N.sŭ:nAjp[eՈ7YZI^9bn ^;H"xFR#wk8Y%yqMR$p +8ƶJ߯z}7mH%ؑnq.AZw(6H+w( 4`4D=>p~7YvI>eȡckFiK΀+'K-^&%4Uʫ-ԤJ:pQ*ٛM,bI^%lPMQV(;CŢQNs(IN߈cRz :GG,ד<C!v:$|)mb^  ;9jRzCs[iJP.ʫE~tٚ~_6 *= JC QHqC乑#q0Ը2#X=>y1LjʶӞD{F[Aʩl'K~=IЩubIՄG1 jRIґ|=W(dVXta@JvJa7mq3*t!dr j+]I짼)]θ<7+;IC"^L9C:_ $J|쐨哥 K.h;u{:}`'SqPKO)Cf8_>ӑvQ8Q%Jj4fg {N:RCT IaQN|;8v ED\TPӣQ2[A;( YKMCZsI*c]N:0vVMD,TzE nf<1盵@% QoOvz}Fx-lc9`2.BkE(/뛢oj.v%ԪI+ &\Li}ISW7$0^l_k26Ļ> (ll{[ꂙ̌y0vүvh&F'kEәtox/xl,gUiݐ]*%):wKeE8T)h+m{VjXV&MTX`(] Q좜̔U`$" %X3ڢ!% NEc;2kNb{^Z8qk~դeٓVFMq=7?l3MX7rZV&=@zZ9]r'ZYMG 9ө̠j%I*}Eɶj 1CR)4Y$==SESC)j<ֹu'wi~`A6VyjjU0*)ŨR#]4a" &;%;5U?)Ѫ8 1pjU4Y_>'>ssu~bvl'Q^mwT) [6${:%AIk H4\ѨǴqѶ;?Xr#-R]s>S1/8)WPI:٫>=9hTJQ?wF$q-¿1ǯ< rد҃}Ϭ{\9͢1۲#ģS% EWw{GDYĶ7apZ_'0 fMS endstream endobj 262 0 obj <> endobj 263 0 obj <> /W [0 [443.35938 0 0 0 248.04688] 20 29 562.01172 52 [630.85938] 69 [543.94531 0 0 0 530.27344 347.65625 561.52344] 83 [570.3125]] /DW 0>> endobj 264 0 obj <> stream x]j >,]\4B ,CF'ШۗhB*9i5V3GbV'&I R P-uqhHY'i$:'JhZ3jTH _}3 ['Q{۽*>7Nb7H\,踞1VAٶm[}U( y%c)v""C"E!;OE҄#;Ѣ8,hrO@Ρ!0>x5vW1 endstream endobj 4 0 obj <> endobj 265 0 obj <> stream xXol=96ć8\b'?ǎ/&1qJgKaC2BiGZ[>l0!JaUjSx4={{| ]Yb}^ߑ?W?8Lb׎lļcWl>s7:@Q9Pb*px@KT2xBjS3E Eww-no[39[l }L2ރP$Rڋǔ;Ss P.LG˛w6?zFsm6bs沜 [&e[ 0R9Pd=حiw9Vd ݑO6~/_\z+W{T hhw3iX&3SL'@[e0D2I%QZB.QOt>i84v'a1~vp]G/ \A XP Ű ` $1i!\N#Rlޗ8SonFm#\f<`T\ _9Vl-T=Ix#Ҙ@ 7Hba d0$2Ҙ M`7|`/RH#qsb BR8$TT Dl[ ۦ*6f@ǏuW:ll8C+bAG h 6,` Y +ZF!薅 V6["5]cx@2 :Kb fjf o֗z5ΞiSgkt7&'~ta21Ɩ Q hcׯ׻uwV$*5#h%7{KoiyH&+U&Qӗθ}u-ѧ5GWD8uH{bbHC%Zܭ`hskU䮮Kݝ| 8fKHTf%`ovhveK/&[[tbm sXkP^#ό1yfQuor*8/F !gn5_8>]k5r8 Kmf!9;d8̻0U3~hǿiwVa(Km6ZIҢ:Qi<xȱJZA 7+*ZjDf[ony]G>gBL?z-C^PKp+IJ^5J)C4e3iuƢ:搻'fxF/T Tɟ_VQ犋lO`(بVxl;Z]?O*TP5L *TPYl~WB _\Q<~ endstream endobj 266 0 obj <> endobj 267 0 obj <> /DW 600>> endobj 268 0 obj <> stream x]Mj0:"HS'cHusGZg<ވ>F.>¨k/[ōFxLC9z;0ьX3 z:͚ "(o\ئ6ࢍ\6/f\!'F&jRJY𼪪`̿.nN KdtD-SJ#ʈJ,ARJ iEJSBHBw7IuHIlOr%%eQt5p.YZ/S ɚ endstream endobj 5 0 obj <> endobj 269 0 obj <> stream xXmL[~ι;l?`6v aIJ/ H VmYXDQMS6MIݏNȏڦTj}h뤥ZMEBʤw;&!T4>|{9>ss.=.tohߘ6@S^Aӣc=c_\| 3KM`q>Jw sw~u|o!m Ik3@{i`PѶIL RR *=>rz)3(ZWk/!WrK|e @@d ܃а]@LM=(phJ8>U zrn/j聂x[;chѿX;ɗ$V rW4`x1Xg.aeu1 +4ž*"Ods٥e&59D$$@˸R(F';ÉBLzi[|&pŸ`*pPH#3XD벬P7E,#'?zďX(c^RIS&EBEC7nm~\-%H!\5@WI5t&XF90 b #,ZT"a䰊3bNC", 5(-ŶB{(=ydD~8jpU8 bcg/*:7N`Y|ZioRb#6~ǯDc 4'6pkX(gU:2J <8wksZ zJC̀hp\"HcE5ȝ5B_[{ڛ<`ÛƕM&8T`O ډ٤њY''R%cᶎ#ñcGNzj,oo*N$'CΚ-oeEWGrUή1cId Abtg8"**,C]nd *;HUpB~#̨ܻd#i"Hbk0IN={!vapi;mn8Xgy܎V#oJ'!TzfB][Hkk:!d K!BDhG깁ew+Z:nJnތG v\& lݪتיּA,N&GNO_S2RiϿH:sm 88h',1R^s?`կ F6#Ĕ2,Mvpe wI|#}:H(H]IC|6fsP[+_Qxc"[ddg>O'*?TJ*U/Kbw(G~ASs(Gh S4N-Gw_) h i5UP{ *TPB *T??1h endstream endobj 270 0 obj <> endobj 271 0 obj <> /DW 600>> endobj 272 0 obj <> stream x]Mn b"Q%RDjɋnA1xWTo\#u&4A#\eN,SġvȊbo؜x-`E5[ƛoE,`Ǹzm[; pj.ڸ.Z<$4z48Vch]B3Iu ԝP!EI%Q2"))?2S1iS/x&> endobj 273 0 obj <> stream xY{l[ys/Eˢ(E!)EI$e-YVC&ɖnؖ&xð kأ3m m`@,K5Țf"r=, ݺa>s>~{%5nùDpH237rG:F}қ9?8\D sSe_>Ƚ>@TU S3$@6Df$ڵ j #H @-y\Z 8#@ KkoA/./=}(_"ٛ?le n\FC(\7yFμt-.+o#((ÃhMV?v,ǽÆz1ڿl[vEm!!S]}#0L__E.M]EyY U*=?3xLd >EZrA"+xR "D? 0s /+ܤَVw` #fG80XU\f啘LLo^f kloCܫ׳_O͟F0Ǭ"حa uڕh,":xa:c yVe,b3Km K^,z96pOIT$ϒ/GWƜrOrC>OOw;W.p;(*p s)ůO))^+S~[9.bZ왌bp i5@2u6"&Nl#WnxoH}b z{RlųlgFRhI+iEO\(h*XsAU[KԇF oʑ-t6? "Q?mjtũFd Fa5e|>27̭Qs$\=T`jPY㞡2kUSn, iQliT堘nS#ERbu!#ڊvS&8:I.cU9B;km]:6|5}sl@vV- =H sN F:5!wظj G}LiUle`h% LHkAnQͣ%])$ekmMn3\p=eYܝu}WVө/4}nA*M d+#?^EJkت 9sw:Ôff?;EV}B[_imTƼ#m#hsQ?@5\8j\UhbqvԲ}nS}܎1F$AĽE!7.I~e$ 6X{Uҩf\qNIu8mcDǢQ,kuaY;TjgLzd0cuGA[h (5kT+q^..K =c'PdHQHJʝvH_<}ԤKkJ{?Fˬ|lw/j݂8 xu hlZ)Gmdij+b氮Dj?Ru/V]8Ho3d鵋VRUˬfdoL!IMf ЧPY)WBfMݫrE= ?\ǫw8]§_xn'OYFΜ^oK,fS=B?v"wދ(+S/3)zX֔켒 S028 犃q *㤅~DwL'7Mo7L>vyo80 p|nv>Ν}Z뭶@@p8#{Z\qvX? ]{\ۨ)B? dWkz%}kY'娋c2"ւ{tJGA!({O+_N|UU\D=y+' ;ŽBH|+L'V{33i4:O48?Y'$McpuϞܞ~g3HӘi 4b4Mc?u@9?d'4i44Ͳ[oi4I(P T[ T@*cʟߧg}'2_au*Phh(47r endstream endobj 274 0 obj <> endobj 275 0 obj <> /DW 600>> endobj 276 0 obj <> stream x]n0@ C4R$]T @-cWxTKo<3~fT]Fè[@[Gxl)Pn$yN)N1tu2ք.Yܼ\5^Z@Y*\q\T9{2@=|!syA󪪪3DzkڐEAs%/D[tF* |LEH (;-{$u9ޭvw}h١3w %2 b\Eq&9,scVF2|藪ɩ endstream endobj 7 0 obj <> endobj 277 0 obj <> stream xX{L[s/6c0 ~?|M @;u(QpX-]HVh:Ңe]i׮ҪMjZmhUTM[?w:&#&M4'~G{@D[!qMб֡rw|fth哣J?\_:ӏd@dr21*d 19Zj}жe ɹї/t (vѥyu:`evt&q*S/!󓲕e">vQD _"_ۈ C?4. 9l!_zJ3''SD\'>z 野k>pGa 1nܼ2|wt0BbhjȲs)Yxtj"1073ܥqup0$#@(wf߃˙| JeF$dRRVJA Z=a~L!9²(Jk0m&1Y,`IŏğWv7`yX!Yde||94zV8YY衐bfOZ$0D Rt G{1 $Ї6! F X0 G!DЄI!qIs:0QL#!͸ ,! B#"nrǺ%krv{hGzoy疮J^1 0&RRG#~  RH`Qi$0 :,`!bYf;@28@2hAeU9K',nszy3ygloj YdU_^b\(s~+so?=T Cp)i+)rnVf/=N>(T{;&"KE^jm4t[Tf;/YTE IU7ޝҽ`TZD[Nqz hd.\`3+W(FXF6\c"d+W##ZetfM[Lɤx[U NK amA$B&0s,#can=/_]*]5j7S-=W7 FǒSskNd#VD25lW,=n y u5[j&ͧOZ΂͖j)S1YH6J3=wH8jռ=Tm Udu,*Lz}iJPaECQUm\չU7 Z&޸vʗIC!""D*Va2)-yzta*D\U~b7FzsM S3}@ 5=lU[pS29ub~{~~RQـZ|8KEeaP&fMr> endobj 279 0 obj <> /DW 600>> endobj 280 0 obj <> stream x]n0E /Ed I% C%bR1q} M.0:Xթ&pUCୱ8ܽ~X\UcN4+,8_Й1zյLw~dy5Lo{oz6L6ע~F\&> endobj 281 0 obj <> stream xWyl֙=sid]l9v<ݗ%]XlRf4Ȗ2:n;M9nҠnhӺl7M@q?HSlwGbQ Hbq)HZ, #}G@. bo^Ệ/m| hpbN {畖gq= a H$Sx/{#aƣ6/=<@|=D--`58pHz29 -4xj)^0A6^sarX.,.A.E(wa,ua(r d=`8Hqx]σHb7bnL 0y>o ,h,f0]@ Gy:@ -PP*Ԡܛe}؎?bgy3 )}t,V 1 (G 8 $]8#Q(cGьJTb 1I=F,0 Lq\ AGy~_;3rV[>b_b˧ZbͶ|bxO>lSM}rj-`sM&[>Ҹ_>xMi{`-OT5y֖'myʖU䱪)9Qa@-ﯼ r[эds-WȻ]lyd:yx}T˃--uSwk͖]rw-w*)Cv5%ɶܺ|[meB-urs}!%75ɍ k rmMLJɕrdcL^_*a}׆J@P>nhqϼ3@@֣0UZ'H!Nmڪj "l!u[ImRVa5YFJwI$%߻88{^_z7[__Ӆ.$ʼnxe}8){/k|}H[PPx|_̺ ;-NuT' I{"rC ћ{TU|5_k)*\ֆɋ.0Lې?L68m |B((7#RU ,|5X>):_SކM#e'ߕ'x<^j Xm?ڤ^"S뽾ֻvV7z֬ }ϵ{k'JIwՕڲeD(("'ZRrJjcBcThLP%IcZJZk(-UU-W:荴G{ұHC+ծcR8L0] i岴vEcd<&kա%qP icr5qm\2ұP4C9nh9mGzr zFX\sl?N0I4OŸV1N8 U7"A?T$PQʭ%u*^F;وSIpjJaVkJYIЅ1RflĩGN ֎G I &qkT /[G"J : .+qSJ U )3`dkN<:a *2!6ĄTF3M'GS0dP,K(1w* zbOEU̞s;T31AR +c어B#ԣ[2b_NG4US:ԉ$t1l; Rί0=I7(8~U4h_Bq ,^G+46h!6[°.Ŧ̙&7F^꒿A_Ǩ_ ԯ#*7l F09"w @ԙ)@."<&XBc#_7h,a̼b3jQeKkɹ!L●xNH[f/cfNuV3,G]6#,%:wr_1TUS}!%I]I&:Nl8YvJҩzBA %*h;2]@Z{@|f"JjV2> f1 k{aL^2az"Vs?Y`{ҷI?YLWw©{?,3wW8uOv[p4w;}ib-/p> hMgatM,=7RG!Gmsi' '"<rl:ODLw~ w']}[w;k-+c/zmY#$[6ǤYa%z3g8H}a%jN_0AoRg*iNg"r|v NvWyFm*G?sM$oZldiR&vF6PIgzI(ߢF[c5>q?mϰ=՝(ڈ8¤a,+L$x?.%A=<4jhy ٌY tcshII> endobj 283 0 obj <> /W [0 [443.35938 0 0 0 248.53516] 39 [654.29688] 70 [562.5] 77 [264.64844] 82 [560.54688 564.45313 0 0 366.21094 513.67188 338.37891 560.05859]] /DW 0>> endobj 284 0 obj <> stream x]Mn0>,EdǁDREb`R11 n_1NS gƼښO<-^!t8ˎQNuu٬sIJ `W==o^7vݭh7s8 Xƞuv5`z͟suQٵ }kdBUUU wDW׫֓:!B|#y!JNDə,#{OySIMcRz"ѴUM1x6ȩac+nrk[? endstream endobj 9 0 obj <> endobj 285 0 obj <> stream xW pי^w! Awf4ot#nf4u10#c $8*$v6ƎĎfS&T[nR[I6Gm9^qe_ki'm'nݫW{#)B! 894#8SS#_=P ,!vz$<='V|ؑm*_ fEP>::Nju cpѽ'^Rӿ'i"<>T/W>59=c *:4u$g'48sp<p?K;<}B#cl>Hjp|kRqikPx}ٶK{i0uF>{䇫osRs@ENÂLnvpf`vdtdLxpE39+EEH !alOJ"o0LnfkhF1 ; |PZmcY!s x 8 `5#c1)DqGtаO>[[qm 'p%.,#=:jgg_|-nj}m |H e\U{wiO;WirGЗ%kv턝;v~}VR |R/>KNpx>H{}m F:wQr=}qBkzkŞɒ&1V<m<p! + \VdJ \DAJt㐧{8˝iWy/TVְ>PeKA~ ])wdLh8\? -x?*B@)w!8mN.CA¢MT(#ǽt=F_=9o{ߟi 9qg6o6C;9yX*T ~qyCןOgO1]/vxP;n_ܵiEU$[y^+/*(X^UUXfe]*q+\IZv+dE.sg%%ŵ";W2&ƻJۚ\xK^YtFDZ޼= }'ڑjWZ|ȼh^t7g;eH0gӎ<`_B;r*fժLGT`._qHerʺ|nV9fjZl6їgkjf_>zqml훮_S?@Mgv< ~dH|~lK4ohMճ>7v@j`U`,YDc15(PFȸ wZΈaY>,+>cÏ]|#.tUnk=ےoi6$ϖ! ~wϾ~kΏmjkMHW "[>ľbrr9w8dߞ"ےxqk\&-YIqyEv*ǵxynIdb滶mn8[2]~bk7= >2az,;=qߵ7L=N$ي]ad֒ln}۷Mor}f|0yą s!A4bhT9\Q0F eRn1Ge#44]}y_Ė/ qmM#-~Wf]m>_n|>tD~s®Mm*Cag$[#=⌅VͬME|$w 4KsO3KקjWmHځjcx!TU>;IQޙlYI Qx{+)r?W%G!kB5V`%9;;h3Җmic[@͓l!wӊݚՐJcspSE|t?^^/|z B?#gNz͝{9<{tw Cٽ_ Ѿ}[[֖bzrRdɮz#^Ov$ m,kE*cuS;S֣uX`zoL~"ς(WM>,/ |muH`OAv4Y i)roޟOYLz)D:"; BZ?/Nݓ@r؄CTH@g0&SR<TdJžȒ%7s" 9=D:t7"GP &$ЀA"1m;"4= GA$ts"/J" DN6gJ$ 8j0[@- $Re'NE[yI/e rœےCaEZ[HLG?R 45^ck)7Ӻ+H91N}!ͣ0WXzL65i <]RP(Z<336H;|J߶jqXĶRJ{BI-]۰Q{ǩH;$oSWfBgr|gm=i;铤a*%LC!KaI;FpبCƏJ^[7;tlFG,FOFI(P+=n1ߧ%6%Qb^LzJ> lb1)&#h>$P,(&GSn! 'rدy[wV9b@iYʑ]fQk@%b"xcc e[0<5G3%f?g endstream endobj 286 0 obj <> endobj 287 0 obj <> /W [0 [443.35938 0 0 0 248.04688] 30 [242.1875 0 508.30078 0 522.94922] 69 [543.94531 0 523.4375 563.96484 530.27344 347.65625 0 0 243.16406 0 0 0 876.95313 0 570.3125 561.52344 0 338.86719 0 0 0 484.375 0 0 473.14453]] /DW 0>> endobj 288 0 obj <> stream x]͊0{"PSk)P`>MF7Ӄo8~8Q6Ul=L{Ly u,QX·;DT2GO,909of` X7͵lLwadE L/Fcƀ6.kU|.B'ԍ ̾:7˥y]uI[is),V%RTJ,!Uꐐ*R:*ҙ(w> endobj 289 0 obj <> stream x]lUtJӲK?)]B[t ,k6lwvE/F'c^L4 >( F v̮X#Qٙs9{{2ELڳW) zj{g({z[{AИxU<r%w841u k8zx_R$'AH$2 uĔP釼!]̻pl ]6Sߕ#M@F]@=x,>?"3U MϜR@:yPg *a3FK QR~/,Q>O~2-JuE9o>KÑ(t4!O&ӟ|XH^Yr٘xA%٨-du]R<<>@q4Q-+Izrd0L4woUҺU7$ NB%F3)b 92@A[+\ W(يH.vkG6A#N׏x̢#'ψ59Eg<ukQ  {oZӜc78q|c_yW;.{Un˴T{뚪:bφ`c^]|XP6+w]~]4]ud1+K+@u#AMTݥnrY2~fbL58*֧mA+mKrtV03H6*I٢`aF&Bd´g0'F 3A0L0Bx؄'9%faCX@AKЖX濰;G{id q5%j4!t;cVc6P$#$3aa/QbȠ.զQy4[#&hѢE~oRi6]49/d߳> endobj 291 0 obj <> /DW 600>> endobj 292 0 obj <> stream x]j0z=& 1C<,]A- Y>W!$Ќvg쮝 Gu&רcE t'㲻ےpY]Og<2 F&8dd_C] WԌv dvOhop JcTnBV !Du۶mЙUv VEhQ!> endobj 293 0 obj <> stream xY{l[ys/EK(QE=(>t)RSC(C'˲"QX&+ &ym30 a]AB )"XɢEXp.)20l}={ιP 8 w8s\ @K?9ιuy_:Y8x~{W< (C@Q`)9;ǭejV7/T9PPr~mn @nu::]pjrpxV]L Zֿ\_{*wȿFW 4AV\@q2p#½ztGzt  \jA/-.mJ +2M^.|D4G[>˃xm~_fYe}d_P(UFUEbh"*H~!r..K^#o@!DjV(ncQeɖZ֩&W莡y/&)k?i3}@&tI uJ.k̴/ l;uU;=GeW8>5JY:cfAtA1F .;D zFdscsn\/鿾|c(X| -;(U\[$dt^77a,"E^+Ư?3љк*;\gĦӡ`3o꓊/<ʨX뭮.Kk` e5*kT *Q=s6۷)ux͞h-)E8ѝÿz{ZL#D_sgtZճpF8pgg̔xuS R^Qgͦm7Q xdV]#`o#\n骈r~##_9Js{|lckl|X@q|mywzW/\\X;=S=u7`z-~]f'qG2':ʤm~%گ֝5vK&aH<%g%Zhu VQilr;&_Qt %pg +@tr]WBߦ۴ AwPX#1He"wJiM)_VZxn&[[ut}T#i5A"(0+( yZ 5L,Z'H4Zq3N§=ֈEh6 Akh_ ƜSC0A0>5dEկ,؎N_`Jר YZ&]ΉGaNojk?2UyM t娓9^Lp#axf#y֭xTՎ՚FckP\4N%wMjXZM3=yr(5RWouvy)M%Ɋz8t'}n4\h?SV4q[WY"yaCd"xЩ8ߨ޷MFL1L':[|TSEAe~=r;(CO@}d_z[5vMBvG3[$ڈ5p$2FyoLV )QUU'ero Ӊz׋'vˌN;SCV{/45e|Y)"*O!?Pj=Aǐ#ԉbѦ>W <_֨6;Xޚfo%f/j̙UqW89{~?.""v{Hq LKM4HwqCcHD6r8OΦ@rߥ)AֳvAPevdy7?5!F%ZDVClrbK,큍F L2Q) )i4}ขF]v<MG\)G38f6rӶ}A}m 4μJ"(=&Q9g^Ը*ʪL]lvH$,KEcBH}OօHPp,̷,Nk:7:etS8u>ɩSVVG}mUʚ2C^(VY} l]cZGFUfEډ ZT 'g^,~%T{^PvfNQ`|Dh7*o5ۭxD'3X" }dc6֋kjw^]S HyITC5"j2vQ,~"/-7NOKb]Ƚw(ն~vv ; 4]BP#ٔ]rL5%}D(Rh Pi.)|QbeGNos/Rf5 FRt4hgZrstQψ܎Z@__ԛ 8IQhcPECb)]3/oz]vu #'gߡ;32_Sljf: @P]s4NM͖3G*h;5K&`}`>/m4N\&0J 4(M`͗m?ۚmgc}i4M`&_I!@%G9Q((G9QrO&v!G9QrMET endstream endobj 294 0 obj <> endobj 295 0 obj <> /DW 600>> endobj 296 0 obj <> stream x]͎ <vрhk8} WdDtOvdb'ރ&smMÏ@;ciy $T*jha>7`m7}Bog: k޽olOW٬ kn6PNʒj{k,6L7+ &X0Y0Cm0G;aD(8!> endobj 297 0 obj <> stream x{ x[u9s/. HAXy$..$@7H")\DRR;VJqIq:m5n:vv\g7NbG &"<f佾~3139s[# @p 8@*Hr'fyԝA;9FKGOӒ]/zO&g}?þs9(`_N~ۑ 䫹oBMoadr\~njSх3XPX ߜPO׋RS-lxl.mdY+HlEض\X9+s@w| Ё0@ƀ,Ν\9|L2 r@o)"@JbeaEHɶ2͆LX+>uk^#~O)ȅ,4@:I n \m6rl@4Bin)Ӌ?M>>G^ _Zsywo3 3Nfq3VJ"&L q)gl1܅B%:\/h,B]Rp<_*8"8pn9HI98 >H8L iXpP~ ! psЗ2L1G90CGE@MT\5 m Wpo_"t5̐Y8 7NQvg4BpN~ pp ,9-,,C0~ej'mjQ>x< z1%:%r3_igڙKX {BR)%=EG$_%=,}KҟȊevٔ콲d{ߐ/^ish]E[bSL-ϕTK%S%K%K%wYdɓ%)NɯKЛrUyһK?ZzUw{#B+m2QiA2`&!H \"c Û.9IH$u$Yɀd`dC2PB2& L 4 -G DH c M; t $E$-$-1^K{i/;$a4}4 {i/_-@2 B\@c1+e٫rP^(!x*4?>;ieH⬙̡={i/Lv찍 {Ѹs%WAqr/0P r^iQ,1 LD!6|㭷~o鷓{77v+M;5&0(Y2P*^1~tp 110+OGV7NrCr${ϕT #p&>hDZ*BBAfeSs X`d#}K#ƖȪ~-2Ʒ#wz,,B2N~0HjDőVje~jQ#Zb@u+1 M&|]}V}z7'ϦϷ9EV$/< |0Bȏt{zw&&_Xw[ }dJl`XG#Y' \ UdwU^? *j:Bnh`9 R8]Ɍ>P4Ou[jiN>t}CAT{58 ,Nk? ~; ѱI߭x71 ^I)wg.6 Yث䔡8p2c('̬ir~HM5M Y;U*ܚ"UkWejs~? J^)Nez BY^,#ۃ |@.N~(NwQMᢷge'uz<} ~h}䅑᳉ I<1U'V%?ս|"YtecWk{gE2[J:KoGQq_OŎ., //^9LV1O@EЛ}RuRM1o+)߄FBW m&kj,Iox|5:~j.ozKN|>k`}&NօF ~ 2KAߐxTrk`m'j-2G(qJ Bu藾>?р95WzR㞔qi¹zcG-QFhm5[5\̭=Q' !l24X=ͳ]CToqr&Wu6>o7 C>~ͤ:k~ s`߅{ƍ.c#:F}FsF޴2^ir10Ղ r/ VfszA1xKUb3Oam20lY, 'tatbFWLx ÛԋB*Z^ZCV yvnDgrLF}5'.W/*ʣާꖧ^ȘĻHVQz14Tv^ŪZ<~< BRR}>_˅;jeU.G϶I :]ǧ*r2-alt:i+vFfd\{~r9z;Bʾ㙃HQhv;X qrwDG,J+Jֈ}6d@ =RURD]>OBFci6#ԕr%嵑?^z+ymU6"[7ʈ*K4oH->mMmԺn;qٳcn-d@s"mmڰ+Ky+%z/,R-@;hZI4F"@ @5^\C5& i5ݸ6&cjZ1ˀaiۂo'gQ(O<(K?ش'&)u5QRٴe9tJ2#~= PV7ҷ ר?c |cTyM[S*e_vq\Yok5Ol{BG5Ƕn)XeŲƾT.eriײkIK^/QսtB D; v{>ų` e냣 X>xc*FQ/4~ƫ~Y}.@5 :]PwUpem)߲9-/3R6ɰ1u[lZ]JpM Z4؟}{\ʛ}o{7шHd# ჩ, (޽yJKq{Fנ4??J\05RY7b%SpoƠ|ћ9ks8|^FjZg]C}lށֆs&D"g&kd8 bT{Q0N"~uOwBYTh/z:>N<:Mj`[̴L=ƍMoZ^!0t{F-rDJ-QR΅k! y00EƒUnfo??7L^ۓXUa ps,VCٻB=jmXEK2Q-O!ڊOGRLdQ]N}k?A:)!I _eXdBcXʥ[ݾX3Zb%eM<ۘ:.vVU5kQw~AphoTnɍx->[@LڼGB*e e"^lhg\p0v0Oyψa5[ p wk> x3EPq&BJ~UfKNोNF[U0bۧWcp|<13"ku6&\E46Cm~7ݦ- I_>w?Džojۃ\x3JgE̅Z)i.͟NÂv"(11%vlK1ƦB&eNV(p';$<ɋpJ{u>Bos$RWg =oXWr zZG}^ԶUQ\cԙERms2)I`9RZrwDjno$z6NZ+J )=y3SSهVsC?@G#ڈ=μE)jyk$bON4FV!h6$z+jq~GG K"Gp9Ez _XQMNj</S?S69(.M[ul*z|&VE,JÅS-Ѿ\aaB4zw;ruydOU ֧cs%NCk[|UzAo7]qSRz8lGf?W8lE]MZt5V (,x)͸ֱGZydOğN%,QEK/#vP{hJPi$ 4{'ޘ}}u񍁯_LlMh/,XGG ll}#rvM<~qm:CS)t6cTu QgV8mg8_Y_%}x|r_ov; W endstream endobj 298 0 obj <> endobj 299 0 obj <> /DW 600>> endobj 300 0 obj <> stream x]n0~ /E/R !Όd&9"o_q~O+K!ss/=yHD m4!uXERwMv2MC>Urg]G?_ RER J2ᰗn"xoJ0kt3.a$? B)JYmۖİy3xvץ,2d׍vjPҠɶL6Ai) 4r#l SaLgϬfʣ h9Q}1U\=e92liezaj4dH96#_ .1E[;5;+\B[ALv2b\8ZVb[ݯ}ޓ ߼cv͎~uYJ endstream endobj 14 0 obj <> endobj 301 0 obj <> stream x՜ @W￯zߡY[nЬ((*KB%%2&ŘĨUG Pj21L2.LUfqJӥ̽s_ݿs9wF@r̙>Ԃp#Tͬil7y#E)3q=]*jJMK3ā.qʌ G{ ftc} 2k40 gι蚈Kڌ{G3kky0묚oP=M-s?z!7Ϯo%ԠpP`dP 2NІ) Կ<@v Nbg7iJs|Q}ոɆ?)UJ19K_o/p_L JBWL(eO\@J()FH{-GY+l%eSTQTz"XFBF`8R a*4\X[P>0FB1d0RZ^^0:Ыׇ cT&WMf4 080BrH Vz>a6ThY`TY Vȅ0fVH4Ȅ<1M 4 SfCs* zsŘҭ`'fCYsBVȁ00ag"hD,7QJYk*u:AGeLf,0s%K-G(V+PF(#ʅOU=TCCճԼᥙ9?uYﾜZ?x4@Ԉ[4@3xiLvޑkB:+t]V載i<>r0 4PY4PP}f`|(\P[l),^4e:LfmnH;?AWh6T GA VGmrÑ},_H}?﯒Gf_(ȼ !LA),@bA*{Q=(A?QQP 0 `440 8qVZ`̃a,a%<kĹe~(v7G`Ca-<"h+f=<`#<O3ã<OxV&xVLMaͰoalExvn쀝a3lCv8]p+D5a,pP`̂E,2Xbݖ6X&L) X-XY,cX~R߉a~ܭVmҼ;=^ vC쁽^ᥐE~PڽbX*GUS ;B( 8']8 gC8o; Np ç%|C/+.%. 7&&E?``:ЅY5= ߥuF1Y1z5 p  ;qߣS d{~dOIxoyh)b?Z:]*ry<_V5l wWXSid7YlQqܕZJ,\PZ+( ])xgBqs Sh)Y(~iG^E Yl6rE$s;2e"wFR JQ_d* 0?/'%"tc^P ,hgJrAE9)x9k^.V &1ju i_GJ] nl;;T')ub/@kVޣVEI%!I%-.%qMUI$%$I\w$ o%$WR_H$.s\]LJI|,I⯒$>ğ%$J$NK$$$$($qRJI-$$NH$ސ1I.?H$H$I5I*8 II^ID$:$. ^%{II,$$^xN%MVIlij$g$$FI<) xBK1I<*X'G$$JMJb$VKIJb$VJb$Ib$Hb$Ib$|I̓IHb$$1K3%1C%1MS%()hD$8IIV5dILDITIb$*%Q!q+rIW(D$FKb$FHb$ %+I%-!$,I IdJ"C%D$$* $u "gpT+PJUPSI&jV _QeIԊ`hI-ZZ˩e׎2pSˠZ4)QK;r~jc 9bȦC%|Z Rkdj!|J- &S SjPu ?OI`惕KagQ9Ԕ)) )\y]JmyMzu:>x<<ؔrRV]GpϛRZ^R\\bREx]))y)9n5Ce(O͠wn5]<:UR-LPQv(g/GQׇQ ~n7:z$>N35\%\!L%%k$< |;ag|B1JL!Y3 Nu b}''#{' %xm$8Ap c(^#x և#K'M; vL/mb7h'M&1m]mbiGMÚ6v5bsX9fy Ύ.(gTv%jw厲͟ՈNcrj/pm7 x؀wzO[?4~ ş:)^,Q&|K5>>> k6Ap p8|8lW+A. wiпK9碠=|_w[ޝjSЫ^ꌠW:-թA6:%ՆW^^ z6՚W^ꤠW'ZꄠG+zt\Уc-ztLЛޠ7K, z8Ao zqDЋÃ+ z,7豜Ae5$AA/e40A/eR\A/RjKNp_qT wD ?B~weA,A~S)hT*a:PnPmd(FOS'Շq{00?~/aY΋lqS]ihķYOWzF~Tf{R!GeJ1#nn͝Rp'N}>s颬aal^,,7rRs6\Rp)ߺtaah5L!=& n9:Z-nwXy_]L!>ȉ?'σbݲxt)eFZX%f5办4-JJK26|q1WуF: KH[Rէ6I26:ԩ#0WOK U9YA=#G8Qo\8bPNCvًg'^D.ci C)WzdTD?S0Wzܳ;?n6 8Ɓ`jֺ;!`k ~LZ>=F̂EʨsJbJ'vcDd9+nxWXr3jCԦI;_0)~ȼ,vZjT*r xcaYd7wP_vC]T̲?}.TwRPr)2+sy}++oe"nѻPQ]Jd@ \@"wmyA8([eYxx|DF)oz |} e_wkbiC^un߁+}V(Iݕ*G߲0(z0E]SO7KV̟0KZ% g6¹d^*㇍[Xmn_/yJk%2e6OI`Sh \R  pHc #n)()2[ڇ{4od=,+lPc] MLQ BR@Г"Oؽ(=w{=ts˨9l,܏`jePB;bhTU.W唒sʃve 0*8cONRUhGZZe0ċRߏ}/PD`'xDDP|Ԯ%mA} {Fr̦cK2^2>wN ",S3-Ֆ 0\1[ݬ3ı ]{*lk'-5lwN6n\Z"m:B> wcwa2̄B,T*k2̒z%P,sSe*#aQYN$,Ee #B]P(YO,s0cOlH?>CeF-=جgYcFg= ,_cVzh퐾q)+8~|Uٽ=)붤hu$ғ3GrY=tJMrOw߄̄YgRrfF% )ʇoL˶ G월D%Y}4Z'd vFm@mQ#Q/Ӕ6lv0 Ô]hWzd}b׸RѮ] ۩sZ%d)J\I [*W *TJɨ*J>VFs~!'IE\m$ōCnG KwDD8B|nzDħHO/0 VPC~PN ԇPhTŔZA32&d쐥,L\y( ]$|O޵ _ŸHv!k AhwUqma B-eb3wVΪ2W]/;`R=.ZJ;VRvGt}K¯*sZcKuòH,畬]¸k3ݚwJWig 3(WӺEa6YRm[[i./5`>:2{uh@~|a"ᬒiMB+(pSB{^QDjJ7%P,/T2 w3do7-*YJE_ֿ_Ԋy T.1j/T; =Sܩl(_yoo\Iu{g옟-#q̼Ml#g Dw%s>4*oőUҰz߈V:38``NmU Uǃ8F(uncXUn?EMItv q--BDUH&}ݳjix^*$ukVJrZj r<` ۩.FU2)^!'LDw9] {侷*_r.+I W}bct/Z% (ع[ >iRg @oaS;)Ya-QPVoP5e9҃^d) '&zCk ;./<}1 7hhc9# G0,cLN0֘lKRB_U8ݗ3>c7۝KrbbtlVaP[vNّjBePF+Ъup#|-R\'qPH]|e'{kҜĘ]HKsznG;})Ï F.'  )= :֫((+"u.26. džBKOwv.}{2d$mԇq[bDK-o7psǗ ʹG67ݸi+8 &Z~(V̄.i-jDEw\^_|숿 wPW~ c 2*;ܳG 3#!3,È8O&O\Sf|S/oX?Q L*`KSOXyLLÍ:y.Ŀ ~-v* dIq::+ v?==NO3Py,%B^c1Yh3~``>'>{B:1d*W$~c@}[x96s5Y#.HcVEc.R6a WZFO_pg5_ endstream endobj 302 0 obj <> endobj 303 0 obj <> /W [0 189 549.80469] /DW 0>> endobj 304 0 obj <> stream x]Rn0+|l+ B"DHPi> T 2΁إf<;ZsFՀ睱<ޝ~X\7ډ4am7,\|BofR;&ޝgl_ecO `=,Ϲ@۾`Z6O2FUZˤ2YUUU nngR2GT"SDQRH":]b^W&A,.y%U $%AHdL$ D$B2B 2>y&r{B'd?L)RAMEsq]cGXonXx> endobj 305 0 obj <> stream xX{l[u^z%RH˧HY>dI~ڲlm)ѫޒ[ iNE>Ƕv-X] 0[wX'mZS!y{I[ s{=> @_ai O^s:;7 Y*l ~\*=M/cӝ#f;<_,̅~@ł_Z|nʙT|2PKWO}\X*u_nT=PܿV\W}C~@'$}9 @ IB=g&YoG{#KR;k׷-rME??]j#>=_Ov6J\wA`mBQy;7N za~=xeB*RA\ aX\\[ZQX ˰@UǠAutla gy*=ҿa Bq50ar82On̂QngTF]Ao`yЃ F?P#XEYC(&Ke)FWJ_.뿸mI-5>JMb3hҸQy]<+ ~X6R4UOwpE,5C 8yc +5AX85 QE, 5V b#8 PR6`P:i&uv*HUN7oϊ=٢5a }=sVl)'2Ow:lAk5D_X ir&3fc1%rBJБ/̐5i|:06ە0t!S{gZ!s+0iNOH}%˘/_9C'}߭|MpԂA'QVO΄WpFN> 癉Lr#־' Zrv{yQWln&~,c#C෽il?W3^x2e bOtjaOvkzz.w^==28ّ.`~5!Q/v2~{_&N`N}w=L!!#m2-݃Gr{[In¤vg"22-͆8YkkZBc@jzz)}v]sGi{oWEbQ-VJBe<vУ9K[0~0c h^ u6=_N-OIMc/}z3CϥC,h6YCrVmet>(J&]5'FRW~j`r6Y:ʺSL$2VS?`R91TOUL5O <~ <5ڿ>k127KLmSD՜: *U= &uh35Z+P@/6=yy%;a=t:ͦ٠k?8d q'0>?>kM"twhؗ4[c~boљ>[=XN9c&sEXr9CBjQ-w$8^εލq,pg-fqDZokxuOՇ?.jҥ f9.iyhC'Sel'rd<T~Ol.(dm`\3l)PzeR])1 ȉ4 "}}yZڛg"m' ^YJS`˴WyQ.44'NA[3ZSd-cΤ]fAEkw]YAȹ/!d!#dy]X-kNʽ"Me&&'tטԼƯ=s⥏֘kjZ5_Yi5+wBcQcmnI6BrUQwcf}Ʀ-cY^7D@}_[RU()uL9SvؕHMw|Qڝў֤{5:Jtn]#H_ 4lìtt),:smuϾئOc|TWX9iFq˗=6%`Z공t1|.uenjKi KVfNTO'L6lO҅q2qdVjP԰[+ۧD9&#|72_H3d}?[R@e L.`mfl> endobj 307 0 obj <> /DW 600>> endobj 308 0 obj <> stream x]j0EY&G^qji jY_'eFGh eBCVe3t_|nj9dB(mvj&{&ڞsȔ'HUy-K32]{9_IRI'cI,x!&ϣztjο> endobj 309 0 obj <> stream xV{L[50l^c ̣ÄGIl$NmiIu֥l(iKtZ-!uSOH4T폵^'}sq<@d9HﯲD 4 |ª 1:=|PWd ub'#6 H Dz}K{``xUHti7ISaKaa udc^B{1u"j>|>ԝb P )#@m&HrgO)"D Z"Ycr~ YH+R+@J7kGOJKg@#9P& ?htIF 'duK(BDOȟ)"J1jZnS%E[%%% B׉>Dƹ<@jdALhP lhA;~L!YDq$3}SkF _n| Oz|+^ÉD}^ÛVڒԉ7C&D=.xV@t w: H2~B: C ]B%A .G:v$,Ї1x0x\D|AD#! BD0YF`خfT5l<0~=$=[ Bfr"zA#zxE8 s"(= EQU=03FI(";j:Oza2,0:No&z3qZ;@b$*~ft)2L&yj:*Xv2ƲryF\^Ö,[pe9)*.w}oˍ =ı#>b_Gx~eM5&lsJZY]::VVZ[ܮK +hZf Y,Jb夜k栾ܑ YYo~,ȱxS}'Uyojyw=fH|evJ9rrr=v p5tѥȪ6w,<6%9:];iw(*KBR'w\%6dI1QV8K.gcFu!6u#!kNT%yZ*{G5zDZ\)]YK wA6IhmZ"bL֤X7(#Jڴ(V^ 0e̤N˨ w{b9HCñ_nO9aWf7>=w_$9yI4?oŗi\PUTbnbY=cƛ羯Xop/<Rpŀ@7_9.==b8yTQ3X,ogk6p U endstream endobj 310 0 obj <> endobj 311 0 obj <> /W [0 59 600.09766] /DW 0>> endobj 312 0 obj <> stream x]j0y9ĸ EjdC|bF,/3 /kmMG`Xq^!ܱ7%QaxuCm9Lϰ{߽Fol[o6`E;ֽCíl> endobj 313 0 obj <> stream xY P\}ǝCqݻCpp|#:)B@P%㦎jGđqQݴθIIne8Ncy*-8;CH&fqZOIg?@ p"6Μr @{wkzỿ2&@NL-L.< %ONe%ov~u~@= \jrsd @`n.5 -} e@Q$Yr/ w/ӓn0\HJ3W ų+@/-.xiU!d2(p @eG{=@L W~ ͅ}r{4[!e@n ADc4Q>{5?LK+`?xaV硟]N~~r Pd)T9T$3 zr:pAI<>Hz%9ZsK&W'0:7sux.W\=IruPe *cH$f1 awaSH!EL#,cn$,<&Q8E>Є9,bSrϹ\_ idp7R0N[9;P융 1DЏݿ~_qDцi,r,^xq^f&oxdm,Z`y r9+RV`aLb`.ۉ\.C |_5\x$ Y!+qrd'SosJ :w{yyѼT}y={ .Ⱦ=ܭ8w_R|Uoy#f18C"hQcT[D($ANl!jzz.?…ȏ"l7~jvv`;~Cep@נODԲBMN$I4ەgC MsGzO l]37c@Prml6K hlR#W塒?LD_N!BhKD:5!sm:fGj[wkVy>9pDI2%@kg]v&CdO>`rgk=ϝ|p审JZDP V ?&tw;@ e6^E^I$jԄ &.t?Җ4xZĺU_1T_<}ARWe-z*~@~C$Ahz4WFG]-rm,@#_p0k]XIAv9ƅbhnk~iaӑau~i]r5Ό|`h[\'j\Nem5_)kHol i^l2iL5}^MoD*vHu ?YMDQ4EI=p& 7JIW_:NUT4?>%e UbeX% \Bjmn!ٻ6ٷYVtV#hyJx"NM$!gI=&8}"]"ģ.W/(@/Qao {۷A.נzm%nğԺ*FՑQr#TW 4Y EB.㾵ƈV~%喒^]EyuYor8vw_W 2:RmK:TMLnvi&m@6{LB4К}zmv7nsZN ,b`È7Ր(!'6ێ)ŻxLUqGxM~ JOߢ6;{'bw~zdE3ᘒ-E+`E6 :&U w<.׮\Wm;OlhMLL7Yk,G6=8fPycT/˥bsI(85m5̮&YR VؙHT{ҀWhYTz8ʕ!j(}M DǼyۗ5|Đ$J:>A<7Q # @:N,6`|kh@^&YOcN+)I! %"n!=)$˧+J4+yEwTB*E׫lIi[NS3^j'먐W^ ZM?(E?:6*TVo&0sU貐[u}.v4+&g;b,ZbvȘҟ2Yw.uvAj4e˷E&,X:++ xX|@m ՒGjwO昔Ͽ2dOadrJ> endobj 315 0 obj <> /DW 600>> endobj 316 0 obj <> stream x]j0E -E+O0T>p+e#+ }$Ѕ% s3LһHgM6c Z牐:J0]iЕIQʾuc }9+>|K_ZV݇:rBC~Rں࣋g41q ڷ@29iVEnC98> endobj 317 0 obj <> stream x| \Ts> adJD"p%22;I1K뤧Neu fGOv-QSK,5MY{hP~گg3{gࡉy{S`ذA.@  @~Jai@`.` z^ (1rD R{1g"<,c!`eحuIGkeET7!ܓdb;@ܖۅiZA<{zAe`[9tW4=R02j)9T2K;(c|U1j6n!HD4Sܧ)eе\K\Mҭ>X*pZI9jfyw9,}( 1٣W}hXws=F:~js֗xwt5]77~ŗG>Hq$H2}hmnAK+hK=>E F1 D + 1 cJ02L3 f e -0%)&#0E2T -{z{ބ|o$ er9ƣ] Kw_xsd 1fL DO} ,צcgb JQ)%B2a'12¬(fE7܏j DgYt6)2xVm|#$$dLdnb|pZOW_Y 0E!$a4#$DO'G, y"oZ$M9O._((FQ=1@'it }:p.3q=Εqy"n;Gu:.m%]d#U=44 q7b q/aq6{}es嘡8<_ xMCeRէͻh^x^%݇o6[n@\8:.\8sŅc!\8rTSv=v6\8Ɋ Ykqr.<KvuwŻmH)Y0. ;0Psa cVr!rA9…d4 c8RlNEt{zƭ3+Mx6a#mGh=B`6mAmDmĊv#mDmY%m0=LCH"(z+AAhүs%?~ J_CC~g5Ɏ)b=Nx 3˝u.zt`ҭLJ!z+0Z @KQHQND!m@9m6`mJ6@ \\tJW m@.mL:1f¡F?Vl :~ZCAC?~D ?;Xz0݈Dit#ӍE7b!%Hcju!~lQ:ZS}a3-D{! aZK-DA"O-DƇ-DSA"c8E8|"Hdo.҃4t`ӐKӤ yil/\t9N\OsqB%98g q$Nqj38-I~8U%8;YAF%N) .lVK+_}O9(=FM఑Qw䒅W 1ђY.wI61nBfHQH7n i׵Qt368{=P0.Z(sA"A(4gi pR=(bVzdLvߐ!2d)!=!]xRGWHClȀrJDXf*****TTN&ͦ[d2YE#iym*UJ$&ߨ&we9bTq7ⱙһI?XM,ѤvNɧbHNz=Ta &Rq ypƫrCǺ2Tqc:nr2G$(8PB8 ?Pf]/|~Ϯ!eB  5#]EUCPcW/C(h~Aڳ+p "с]A"he(vв,# =t2b 0@`?g" #b%щ]Bg%l]"q7 ]D"LnH`g4tG"~BO{ ѝ$`?~D_SЋ{ЛT$><,Hf瑎<2#)dHe? iΡ?9 @;{eA&;b0,y0Evy^=~ bg0Lp;Ӱ#p3 i`(;g1RQ}B cwط(}b gߢaAS#s)FS$ơC2f'gdI\bvPN`2ưLX b0t<Ďc&xq<"Lx8fa;2;Qa*1<)L;24ք'05af&b.l5>ap]8N_:V&leu8*1lcu8` d;pRSv[fdqZ3g=6 d{6> ?b?ۆdV\Apm8Ķ2-Fۂ2_Qq} oN9?yNnO.EN?ӏ[G~w9IM-rzӛ"]Nosz9}9ݛt9~鷺NtoNo;@N,$yONyq'jm>>u?K^Y[p[jw]Tw]}/0ui]?~--FQ-/,Zp[jDHȭ/׼mjmQ\AӂR;Jy# ⶡ] nKw]?--5Ve a--5NFܖ`e ܖj6!w4/([p[jΝoƋ} nKM/n --5le wԜ$Zp[T  ܖZ`wtH^Hjm99!/a> endobj 319 0 obj <> /W [3 [277.83203] 374 404 604.00391] /DW 750>> endobj 320 0 obj <> stream x]j0 ~ Cvc\9t6sۏ8$~秲&t֙Fh%FABe}i1PvLq~DѺv7 m~p@!`GeڠK6͇l6Pf.V7pAgO]ż}+ /xtHfo^O+w ˇ%}=ň.帲ŬuH4\w endstream endobj 32 0 obj <> endobj 321 0 obj <> stream xW{tyٙJV,^3mf%^K,[ٖwZI6%ob w!8 M(h^>=)&&isZnsv4;}̀8m\Z}`s wvm4@:n 3zr_4|{p0269wpс|q(_X14.nH Clu__ޑhD9492@8E@PFGG5@?cnx0 ty`(.HR7N:y_|48m+oݜ}w?}hQPm|6-(xOHW\GWiy_M<\.(ߴ,-N˻+ʴA 3w]QgvUAw~sj;<6sёήtdsM4/;?w 0Gp^ YnG63OM\px%$.9Jw4Ӭ픜z'{EwP'Ofzge0LB}{(!:j֍acc08P;q|L򦉶aSgנI )F HA<([^ϗqFue)DMWiY1H~M wRL+x=ƮN=},|ԫJL' t ٘q;RSITV-!) ~4 ,O|E4]zdlIy\Y3bƈZGVHm O0ZKB)ADj8:Օ rrr'w\ VUVjhNa.qhj,_GD^L=zɃN'] `!uP5qYJ 1;ҟ(B|O܋xG’d355ͨʄ|oAMR\SA"-WXYbe~9HWv̔=|RɚYw|*+$:)%2YR#́y&vj~`sc{ǣzo!,.*ww>ޒeU.`orb9 1`|n=w~sϗ_Ttǖ.8:,TC--}pDT}g[Z9;6a<@8 PF>MA* lD$,꩓hԚ{BJ@sͯe *whS&OMW7O5Ͳp]!%{Lj34U @+\_HLBDDz%E_ҋ6-I2PO*\g&STQ! CL;B/ n.KA9WGf A4)4hR9IiѤۦҋ3nD^y LHL#`0K%#,ݯ 2B}''x"+KrKqdF%0LTt=Wr04:v6]!* r6}CzoEi3d>%j,33<@(H)Ӝg6x5a*4m sǟ?-ZC?t6"QR~.G !:tnH:t^MlWصBE?J^Ә>Rjݸ&6T7h5''=*[xT Tư5Yq*<}&5JC۔ %!U)Tj@kmv,JL*@D:CQCĨfH6*fנf$FR+I}Bw *VBaTG MUJ—:T 3הl, RI痟.}¯vs EGM%tAZ< ;yW9`GH1m ]pL7`P\.{-Ͷk;u+_Y:utA ™.aMq8tJpx "1:TXTi0Kl `Xc4{7w4i6dk"ɾٵ0ᗋϙ쐤+^2f&sj`5â;+3.Cok93\QsGj˧D+шB; +jv-vw`UI54Ri@(&nP(њ5)H{Yqk쑥&⢤5#+Ypn QֲO#'_,Xk I>%㧇LC0ۓLϚbJa6!}M-9sgVfqF~vh\[Ola{ڲXkKe;4ǟO%諨K_eNo1(ژk7p+,M=fo٥M]:|֓4-m' ;mWaä0uldvRvf\35ͺMc/zm"$G >ɤ}5ϧ?Z .F@bڲ'?kAKz(X{ֵ989ʳz]Ͼ_ػ)@fzNb[q&5FIɼ -ѽ:NEe]&DJ~ Kj||g{7w(#T'Z V" vy;}Ɣ;qgOH*d-?CZ?#PQ2) 'vMltYͧ$l)DI O4MNFEpҰ,[>G;gdZM`=l))ђҎ,IjGU*kTQvTORӲK475d$QYʾط̔RSS /L_,e?N~o{X;!kqtJl ~K=џmz4USXgR[$g؄a, endstream endobj 322 0 obj <> endobj 323 0 obj <> /W [0 [600.09766 0 0 259.76563] 39 [740.23438 0 0 0 765.13672 0 0 664.0625] 53 [660.15625] 71 [632.8125 590.82031 0 564.94141 657.22656 305.17578 0 0 305.17578 0 657.22656 619.14063 0 0 454.10156 497.07031 0 0 568.84766]] /DW 0>> endobj 324 0 obj <> stream x]j0 ~ C!к ?,8!o?"`ﳤON5TZcqypXI@[c\Vzm;3?AW\15zc;xzx}s{+ 2._֕FLYE|M!!nԠqtBY.eYCg1ڪS\D3%QF:Fztt$v QZ%(SWzw~4f=CeXps7#ť}4KX~X{Hh,>67gl| endstream endobj 48 0 obj <> endobj 325 0 obj <> stream x͛ `e$Mh!$J[zQ\MO hS )1-EV!Rxº޸2-A<`[\Qu= y 㝡|̓y~L- ft@DԪ̜o.-׷0\i4.YdI̧-< 2iN}{ (y˚oz׷4_? @u4Go``EWÀ1@Wͯg`_P?)1'E@Qmc@}Mmg1@QB<"AXiC!L41qxZ;Z @Ik]6OMw}w[|g4j{? Qڗju^`R5Fa߮HbY1R6D Ntjrr7Q+|QM] u~j4:lSvBnG*r0 P*LG=d\C+ڱ ۂA*)b ]p6ʚhud;3]DƄ]+îG->MXvE+, E>`GkaG61ZvbюɘF,VXQA/0x\H7BiXPQy;9h"k&k3Z&p>zRvGSQ4>\-bS?:=@ uk#̏tͨA]cofwy@U^40)&k b?^ 2P?ކ8 x<2c0UMH֐4 &GY~-bSwgAFރn9₩fZC@wϣ1^\&44cp j1 !c.pڱK W`9,r\`ٲ4\p-6:\p#Vj:džpZ\jkqvEylf܂- l&܄͸-\Nܥynl6^܏0 ~l#؁.܍{ȣ8A? I2RQʥ4 -*b6`1Z8Vk]Jma\5XO+p6-[fܦwZSk;Wk\ #x;Ѝ]؍GC=pZϫZ?^<~+=2+dz8<^8x/ECxojw |/5>@s|p5N$N 3dAqԛr)_#- pl SLVY+L'PZP%c2Dh}6)z" )@/_<{VE3k|ӪSL8||YiIqQ`1G1ג1n/uڕ%NfVvg]9du)ZTq82BuRlIKgi]IF:uEG;2],H2EǑ&Q]&mUZ/+QP/\u`Jyߊ)&#S,\Ħ)%ϒ3KtgI,HxϽ)zi 9y>1AUuIzP":?C v4غLQ:fIVk:x͹5Uu?KZ{FKYjWĔMΒn|^s-,u)T7W]JlSEgWs0ʧ]LI(VPJ,-Qe/+aTrV 7q0mg.Fҫا)>Ylbkl]P}TfiUR?9ԣ&|UzAkXyh 6F͖sY4FpY+-c qj?GRDWqZ%5v!cһy}YOcbZJ67u0ۯSP"ƊeTYΫD]ѹ*.Bj *>gbW>unZkT9=3}ZwɴXsuaSi>,sks 'j{T{v;nѥR&o7,#ʜeuβzj/;:ζҺQj r7Ʀ vVqgZQFz.'r=V~[ k n-*Q5jAZ{7С관Vn~Ŭ<&ѯc1SG}֖e57+jZ:jԝ^R)Ep"D9hg/P,nP"zQF]} u92ҕ6bvi|c5U >%2Ʈ]kU\㕎zuF&4(s*%UD{P"\e5꽈j_QSTh9&M}S^*(wR )O}F5qmc\JkHDU>)pj"E(zWS1{С?Hl,TSt)MW-\ uZ+DU">UG+ ^+ 7P"]V%ڥD KvMPǢ\(~J?VT)Br)&ׄz]D#FF3qMPD42yGFSdPoLnt^P.JH7^5iN/`e4-tHtf "" !{ۺ3,&? eDy(J^:xdЁQ}{0'7;+K6"]CD`KԧK6v1 A ȄgWbb$I~RMA~zm̊y@W&IpG&~ߧ"΋c˜_[zc3n)oXs!"o`b` 9G.Yӯy9*g6\tS/n{;,O2KSw$Evv'xH S!`:#Z$a]1tD?tbѤOꍮWSn|>x-ӽbscYH5VKU[fe0gw_P2%µcLt˟|c;,7fju b1 uIL]g#:]-m10{Fj٩#i/W)zk|q`Yh2*3뇏~kWW;]ֱcqT[ZhǨ˷|>.)cU7bbϡAfJL蕤/`>b_9I]u rx-v }M3 LCFʋrG-{ rJII;$_btM>WIwVyMe9iQyQSU)v>eUm-o#D ܳ_~AOX30-+p^VRze3 g8ƎG&JY#%)CT='!&D ΢7t6GR$E""OETFi;*mM(OwT0Xh5G^=TzμGq%&r)ngE%ӲvS֌HNo\1Aqy 7%lݧ6h-!l{<=d#!>i&/"nSB|2qԫW>ǻ{%&UFIt[LAґaz|BBz/d zd>r9~s'~.f[c!{ U5h}>;+虫}~A[-NjG϶ܹM<. ).}o@gtFiH*؝yYtp !{)G IN2~AY \XyyaDZA&$uv((̞տH v8aDb⒄wv4V~oY:'*0"]Vu~vEGL`" ˳ͧ\Cާj7 }#=wlXO1䰚(d났OuW7}Jy4NdOvCĠq^T 9g~GުQ }OS>n7\>혰N^͚Q2qtnt\_qWd2M qAX(%,{.).qo|$\r1.G|\K._p.q'\z|#.r\g.rw0 .\^r˫\^2.sy.r\qy\$\ಇ\㲛..;tsp\Ო\ >.rol㲕]\r۹e [7\n沙M\6qF.7pK'k粎5\rYe5U\Vr˕\VpYe˹,岄".\ri岀|.\.spåKK#.\\e6Y\j\ĥ .ӹTs˥K\pe" \ʸq)Re,\2p.y\q%KL.CwR8BՀ$,A5^ր)A;5꯻ WpB{j! EW2tuJp +&(\-V a[, +*CXڵ+@X W@2|$,AبjVUXYXjX K݋T(PR=')Cnhϩά+.Ι]-|f6jQU]PEhǛQY]1m*eNVNʩTQZ]Q\]QX #-e{y¥9/\村1eAp Q uu/ o  g~&N3w eJ~ 'f8p(W e × _0|p3O>3RS 1| 1]?16a=Z ^g#k ^exe^dxy0< ax)'2<ߝ\(qv3bŠ0`x 0lgx!`>{~po1le.;`6- 263İa#Í 70\p񒟮eXϰ kV3\Ͱa%U W2`Xp22,aX̰a!e m 3c - sdFz:f3bea&C Wuh`P0PP0a dI  3120312 1e0aC>Ć0!aCnwbEh0d`C&PΐkHSɃ102808ݱy'1gm- 6> z1$2$0312X, fCL Q FA 2 wԯ#x3#`H[L@1d2}>LC ӟ!ӻO6d: ނLoB7 !:d#dz 2LBW ː%"dz2=L ӳi?dLOC ӓi/dz2L~8dz 2L N v@CG v0dz2=LC ӽ[ȴ 2mLwA;!vtdnL@@!ftd6B! z L!:t dZ @ՐiU(+C*+!ӊBuy(B<ᥡ / ewQ(. e5eu^(zI(sCYm euN(͡6*jC(օzq(CYjm(2Zʨ/Ne:ilzC٬ e"ͩlN esr(CY^Y(cE2e Le)?,eix(Ky, e)7PCY e)2 ۽=#_߻ endstream endobj 326 0 obj <> endobj 327 0 obj <> /W [0 189 549.80469] /DW 0>> endobj 328 0 obj <> stream x]n0 {"P%@ZZ !1Z$X&EO]''$e} \Q7xg07_E17VvbO2j׍,89?f†7o[Klhn %snc|iv.l[pe{)e# SI)eγ3③kZI3)cJ:"(I HڣGP*&$ETJ*IgTJ'(3)&Ŀ=f蒪SX{??AE>oރ :}LVb endstream endobj 72 0 obj <> endobj 329 0 obj <> stream xX[L#`sq/\= Kr[.^ 6Y Ji.6ef݇FM!UU5QVԨUC>m}V3? Z<c'fU@~`hbUlfe s\ dP@32Kɵ*TrsJSI9W!qtiǼ4v ݙBr1Z T7\6[w2Sogm\;zd 9?@%0C3hY*dвTH%,X e#Ÿ]^L .MPЗiHH.OUl'(X/@/ >7I s@Pj@q8$RXFE,][2VQy|BAPalM`_6E%Xeݲe tm9Pl`{yΊ^/!": X@ a)B9xЏ2XP*XtNBiPĂsW $VG<6 ?#klY=? 1#yJE,bXDbCQy6Dz<c':b(" SHaMeCb`1$t7@, қ J4@p*:XTe {`ξθ/3{H;dM!6Kq~Ѩk{I0%n2kc/?l ݣ&=|Ol8.b]tʯ&n2'N ǑD#ݶ_L'(Ց]tf/ Ba/kK9Upjr?xcnȤkh1Y؞IVeT:]ӉjΩ ѽϺBzњuj ;Bv&z/ZK1 j 9;~e 9`[PZXk#OMGmFnf}E>~ӟA 0=ȕ Qi .EMYpQԶz[ooMcZ Q aW CX4)G99vet]%e 権˝b\[T۪ǣl sF<.5OiTOv+BljjT\o0t+&B̥mm{ 9.`<P ݏtĊx1VjcڍҺZA#E 1ݾn4Jr@52㘣\gt(N;Zvɣxަo[-ӛ}jqAEZ.Tfrٖ#&֠X TWC yuud  x]|dVZ qG>O*liRgm3N>7z*= mfUMcJ象愮FX8ºN"Qb Ni,ʼng_h֩m1M(;Y[k?y5ՕOWMom4W<'dCK/PӨrô8tp_0P42pI>%R+%D%J_ /,C A#4M |!c"M H?, $H0 $H A $HMjY endstream endobj 330 0 obj <> endobj 331 0 obj <> /DW 600>> endobj 332 0 obj <> stream x]Qn0+"$i !$}4B-cs+I*`[33^y^5U:ciBh7QhWCϫ^Ce)L/9-^75׳s?8 XƎqòI4`²_2NFkR! -˲Z~SߍnA*D"2BGB!kX9'I(9Dt[n~cyS>jO|%E$K:otZHIޣ +̚87U_9 endstream endobj 93 0 obj <> endobj 333 0 obj <> stream x͓_lSU?ۮݖpv?ΠQueM[aHx/$1 FȋHԄDQki&_r|914&Gg4׀؋\2 Lg1g'Sd^ `TwTȁ+wbb3Мɕfk>56_fT<ρr<d;5r2oKi+>_0O@G>~ ¶{vR详!皰 hnL,\#Zv9%jp_(vd_Gn8ķ/>?~4pua֮7F.-Q@}2%R2+~Y&F (:1SG Y A +$xki܌brѡ:T+}x'۟8qkL˸@)muz>b dt+efqeqZ%Ϩʎ ^PqtI\tNVۍ5 o{x} 4!__:%*BUz]Zïu-߳'&'^?<|~NwnNȾ+Wy"㱕by'[b[dO\hX|.qhsw&"7[ 57u 5u !=ɭbzN`UDָĶI˧7>EkS8>5¾iqFշă+E0El`%"ZB>Y'|Koyzꚁ:v*7e==55-[Q^HT`T\|S:\` vU.u߅Խ¯^qG"K=L3E($4)Fx)LHc.Ǥ@i,f0DJ1*\#G*&ĈЫ20-Ƣ>5K3#==|VRԎcOIŷ*KD'V!Q褍 3M 1)*a*E;Is*.f<I4 endstream endobj 334 0 obj <> endobj 335 0 obj <> /DW 600>> endobj 336 0 obj <> stream x]j0 ~ Cm`( e}VR"9퇝>utd#tFK&֠,cuSzVkm8w4:VU 'İb܀G?`iõ?8#ELJ082^)fe Eӵ67Pf.v7\M*!PmJd͟v0 yP Q dznwj2^!%b+[Nf-#Q|RE ww endstream endobj 99 0 obj <> endobj 337 0 obj <> stream x |S;9Imڴ= !-%M@DH郂PD S7:霞dAVlN16Nݬ8C\خ{C=?O `>` h֍n| ᶵݚuRruY@ :Wu0КWt \W ӓ]NL<@0U(c `rޫ;05W<`'ֶ^ݭCYp\޺#8 WƧA.w_ѝ3>0:Ё 8 K fA@Vx6Pr_x kMc]L( Nڧk{0MdNpLyPh^e(+= 6uұ39<2J rXxXЀB.B94RZ :`\pzvJ=S/uqIhm BmWlSڒt!/F>xU E vؙƙk ؞f`, *Hj.@+vXp*%!J!P`Px- `Up P//B>Cxq3WjnzmTXX`%tArE=JCC2$ 4&ӭKfX{{ʥr/*WPխSճ՗plc/ +u&Oy^6+e]3$t{pbf;Ds޽{ [SkX,p< O 2 w>8u8 q2ԑ05⿋scB{{9i\?Lߏa_?`8n5E#%$Z|M7 հ:;M{{no6n;`;߂oý0<1QxScxxrGAݰ~O<as3x^"OSJڳp~rAn{:Vρ~zQ]/+wc^_¯ oq8'-#|*%«'$j:N@db!E Il![a36wwv: ~vxGNo"Q&zW/y ~qG?W\8>اQbހ6>)9R]x>ѷ{އߍcDu~%=?)%ߧG#@(a G4O3%4pF!q%T ]~_,L,칈QN&iNMI=M tRJyGI )%e\*RMj2,$ dtnK֑v_Qtyǟb\? f6  Ԫ*=?3g/H~ zU /._vihiKsiq㢆̟7nX[S]U(=kfY錒ž#WE%RZҹ%{nԷ%5cF~@u cZ=Wb܋\8;.A^` 恋#oX=018^K=^`߻PA)pFҲl֤dhHociڠ]e2k4LeTC#R{c!KoHA>8-k.pz?E\'*OcktgrVٜng˿O^9@)1HhuSpWvv:0 :MzAv|hZ%' &p*>-Ȅ[Eڂc#c;4rtR+ȷfe&eeg2ExZjldR$Mbn]9,'(O/iR284,rW,gi vwW?1'lS\SʖlX``lל0L5IΜ߬%(ϼΚ`27wE~=QxZZ2YTdeeNnH4>oԯZtsBoK ayLl3|fy]&D$Kb 0C\6s?`ai>W~%Sk.T:5%oQX1X8;"ז>YrÒyr^2ϰp58:%uĿ3c%c=#%L2-gO.UPA}?X m"_䔤I7 ڸE+ ;WFbk-# Tj%I_L<8,0h{Uy/WFjj6 ]`wi(;5^Oֻ;k'[M_;W?\~m<7~Hf^AT4)  %{zml򂴖VpA}WenRdQ3>ʯSdޅڗ^vF3$]zS`dflS$mf'ef$-㌽~# 13n7uS1RhR3i_BN3Y'lIfzl6I<DZ4G8̓)s:rSSsbg?> aEsDA _75Ty.( lBEpD%T/lq$0{m) b=l챽1jr3u4Q?%]nZ\gӫbb-M,|O%sL"p6#pЕYc]heyalʩWVd4-LMRpJܷx%%)?š H́QZ@)&J#ƟqQ>K OnQ4Om}^/L*3ohS+,`CC6CזO5wsgvV y csےQj:NfZϘ |EPZGG,yO^K`I|ּRu;{c [WlU>o?D>OؾI_ih۞.bN¶'5 u8epghe#5C@a,(**XR4*VߜCsBJ'={7TJTѡ'#NncNM/KԵHj"Fi9-z5e:u2h#3j͞\^03/ݻm;7Ḇ;<#%'hѬ%PQA|EE#$Y2ZNJRT4i5OnzbͶc/mV?@XiQN rܯk5K`RB;{2:{x&>kn掼ˎ'Gl{s7dcz .jȌ0*WZ;nb5P1R!xcX I ;Bu3!X31QaUJ s[C@uȟ9N OUj? B[\?X`VE!-Qj1k,10m򲖖ZG&$)bJRDMyIy+gc[Y&ŻvxD[s+t/ɩ]6fp(k3h Q'P5t9|3= 򛋊I93u8;uxęt)ʪR-O.^~ٻIWo[uWdTx0 e yP至 Nש(Gcc#.ȟPL"Τ~&tv'78[*&{O*o|-?^r*faύr/T΢7C;&~a};΅΅~Ѐ/ӯpn7 @ ,>h t3to!n0 .^G*Bz-MJ#6A>a 覛`/+!&qh F*ҹGt#0%%-z5Sޗ+ N7(l3;*R)\iմmojhj- 7 a_./\t{ o!Z%%,65 5bocKDj$7scw#ey꽁pRnV65Hviyqh~z宂WFҝbΏ8\BC"u!K9F2s(A*#H92DʐRdRLGiHR ɋdQEr2A HF&#.dDd"Hz$XR;"6$IFĊX3#&Ĉ=CQ#*CXA(BP q$"gϑ3ȟȟ?"!" #@>BN!"#!#!"EAFNF3( r9Kuk1U(r9 2"ryyS'!Yd9@Aȏ}ȓ^$كES^>Ec^G(EC^FxQ;^E=^E᷼(Ëۼ(E7(E8/ o&/ ok^~ŋ/yQx_/ xQx(E(‹˦) h MS@x~f ϙOM'p5aS@8h LS@2U O*cS@x“#S@c OnS@e S@47nj!Ɛ1$1!Ɛ1$cH1$|V V 6eX-cX-mX-eX-|ӰZӰZaujjkzpV5-d>Cȸ=҇i4>oIB/B?mo nMvQLiSE)Ӭ)?MgSi-l`lC6&lﱕU)Dӄk(%%S>+ƇvY3nsof535ɩb%ܜy^i__yYO/y`ӦLo SnDv%D7z<~DJF"JԲ48Hm/K([oRFcPڑ<_k J~" c0{z-,]7$u=ޞ^8uxpV{zWoo<ʕg|#L==J endstream endobj 338 0 obj <> endobj 339 0 obj <> /W [0 213 549.80469] /DW 0>> endobj 340 0 obj <> stream x]K0{>E_}V+x8CL~]؃$xyUTj{7nPyIFv!cWE̖JuKνٚovіyo%3oye^}FR yK_vUKv]/sgȩY7LzbB<)˲LߺDڭ_qa!NqN{@XC'3**)=ZG#j r  9q^ "@dxqyt!ɳB='TVO9Gy7unڠ׬ endstream endobj 146 0 obj <> endobj 341 0 obj <> stream xݚy|UOUoYzF1T4YY H!ڍI$QAww* j;:セ#ApHUq;s~9N=u: `D4Mi/k @S˜NWT O_<om3mW@\Nd{mmpHyiom}!loomNX'<Xgbkݹygw45d4_љ5p9iE/ s:;?c@gs[;vg|dxAx  =C ha-FhQX99>SYǼ:SIkx̳UYW umzw7&'$A' :關` ;6܌g/g3ޟMj=Ra 3сh c&`.q|yߙ#-}^k4ПՏ,>c1I+ӭ`4uftqd,93,,"06:ؐs=N7hъf2Q(EA|/!Ʒ8880NAi e߳l6$[LJ^' D`:ㆰ_ C[$K^ !ΐK %_4i~_o}ݔ&4vBMuUeElc)=jdIpWY93C$՜g2:Q U;jJNqֺcG]i>-Ф؛J/(&=vW=ݬTOb+^+M9U]|\gg*BMjf~{OuS+z+<'T:*\yPrtYIszeY,+ulC6bTXjθޛ!MCnSf+GY$*Uʰ+?pU*yj%QxO]}~iE NPUSӤP3w(JŠ_vu!7leY W&eoIkT[S79RU7žg(vWѾY+bNS]eskT⮲W+ؽVW;jNCOwt* Sﳫ5NV*hjWWy٫{XXzG>aVy(*}S)SVMmv_f+wZj6eǙ揝sV7޹iLѯVK956ՊV(2X~1ΩZITOgH)3ީN˦&4^ZuZTK06)swr&iWtN"8+kZ :;튻Χޛ:Z}= O4VS2G})BTRkOЎOy"oudGl@؃pNŐ3#\yTir4;6{MOs(,vtV7(8|c3Լ%WJbpNW i>%.oWI9AnR ʲf54sΉ-~tj@9+qF;G}k7;4Udf+?Wo_{m j(6>GP'Q-LSwV眤"JM1Q;[d- ؋4>EZ}.Uό5B-љ`W+FuLQ4,yhu) N%.紩JsbpV⵮aC:PHQm$TΉʲ;?Aw:FM "!65w蜨Ωȃ٧mpXn(kY[eZa_ri~p𝃶{JJNҾS-Z\T2bK%E*Ƈ JFtD_N^1V'=Kݎa3oo- t{rnK3O'r5 Wmq\\?bg_r=^<_䠰7Az6-44Q?Z0-ދ⾲RA=ZCr&'Ǔqp1"SqxA<^.b<8j_^0輑U*;P0-yډCIEO6Ԯq唕֏ LM񯇀9n*"#zBMi!NYqMo~סLTM{/ HO*Nr :R4C sj?Qpk]₼ु7l];!L_ܬEOlMoY9,apoKLLC& ӅIwZuӝ}l^ӧ&Q9|uR l5¨4i`826A/ۼ)'lkZԂq=sSG㢽R(l,pDk܍kVrֳ7NXΕWY [S]~R^)DAw%!!шiɔr±(SSOJ./-+"^;&9Ba8dQvZv#)$Ė]Nk[P7,UҦN|4똲Һh]FKd[Z:! J-qGq`]1c}|rǧmAs\_Zo;-씢Kߥ(4i\V3-Y8}׭#-0댢3 s@0\ 3p9B՝n67;.ؐ,)Pg,/)J󏖾}\f'Z1ӵ8}X\4 M$qњ:dh}њlZqiP1gO^>YKHy"QU9jvQ?*+AL'^aӑ@[  :LAL7';y)޼;7l]`W1`xhӈ곓 _.,yJ~69HPA*6w|Y9~R_5}e}=_2-,EX| 8ΝSy^DŽaήRIy_7]Knr]+/qm'] w:WQ4"&uRR$ )'|JԇWBE|J^ڠ?^"69&x(6o傁׿HwwKzQk3Ѐxєn5em?&ƛDzObuQ_{ޓ\j֛S}A䔨k-i'Ҙʟ}*% BχuuooTWxMaaV,DCWYH-Ҧ$N7z? ٣j'jbq]W}]{l\E{  k2%np5nx xa Erv8`uqFC\0EuDՋˊyEk;Qx /rW[ؖ6cKO8K8{}L0>ę`tx`d$>׽ԙ#GQ1}> _H|7O}*:Řp.K< Թͩ)'р"?> -5>.DoP 秤fcQQ~qYihH.-_g)hQaAiUZ~"Q)#%_e*hTew xU]:VgCwmnv.2h=$\ bB.a.\Np9g.?q1.?p?|(#\rKC\._s˗\9ϸ|.|#.r߹o\W.ry.osy˛\:׸e?W\^"}\ry.s3\vq9.ry\ⲃK˓\8\q rp1.<.sy˃\r?lr/\6p]\r۹V.p#ru\r \Z.kr U\VrYe9\Ⲅb.,r\se..qe6K2K;\ڸrp pi.st.rsq\LRϥ.qe\jTp)Re1\J2H.%\Fp)RĥK|.÷R>J $,D#^V/D[uWpD Wcp5lG^XYX=NXeR^p K),(, !`yD!,eZ',F[HXK+p%\",GBVھCԽ0 ` s\˥˄riq%7EMMeM%E7JvN:}/ 1e8-a>C 0kds>e$8h 3|! gxo 1]w0Vp)Do2:k 2gx/ /3"> /0ax v1dxYgfxaC(Q.I'gΰ!ˠ0lefGax!`>?1lba#{fN;ngV[p3z1epCO0}k0faJ W3,gXư*% 1\ɰ  1t3t1e29 .e0aCC+`hfhbb3\0 h ghdegcpds< &22L`afbd`(gp31g0a 9 i0aCq0. Y!a8+:$r);aX0Y}'0!p&aC6=T]`*`d0!!aCC*C C2C`a03$K`gc01 z 0GRVoH'#z'GꑎY=V#ꑾzVtꑾzVgHG#}mH_Y=җV#}nHY=ҧV#z#G>z[=V7GzjHZ=;Vt޶x,^MWz^x,^UWoJX_,^eWz^x}^x=+v[]╞xg-^Wz╞xx'-^ Wz╶[6W ZR9 )怴c怴5I9 =hHt9 6ҽ怴6=t9 eHwRHX2gKw$vH'vH%vH&vH$vHLnN'vH7%vH;ҍ = =z$ l9p@!?,cJ(秗ҷ L3uYꖥF" jB]nMRiVѲ"n;-Y>nYDk152FTwBkgwOS k4NKtʩJGVGjō*enՁ nWy]]]5oN̆ܮvuuuwwuvuw>Քۥj[zԭr{]CyD! d LLd:~L?A!1d22}B#[t2AC5d 2} LC ӧt2} >LB !o=W.dz2LoC ӛ :dz 2 CW _ ː%"dB > endobj 343 0 obj <> /W [0 84 549.80469] /DW 0>> endobj 344 0 obj <> stream x]QM0W̱=V-P~n@n`!bF\Co7^6UcMGbXq^!<7F[ 1^6U;Ov#saw{v3>m4vҽG١h ^!$i5jTBQ@^u]0_?%գSG\D :U$)+!ꝓ:l~Si鑴)i/TQ"13AhF/0_޳侅ޣ sb@K4ntj9씑H endstream endobj 147 0 obj <> endobj 345 0 obj <> stream x xUzMzK:k! lH!@$THXd"DQQ\@TpdGE523 ]u :sy{>I:ԩ{" 5%ά?f&~v^ζ~Uu"iLܨ@WRI``2c~C{NVEM?j kԩ(ݧΜ}+#3'/~ofM:[`vf}LV;"<;3.R~ӬB!&x -D*H&Ԃ@  Qp :7P\-*&I^&$àq𼥗wZN Tsw)50#YׁԊ. ُPjcN*{)G[+l%F^TXOJD0c,ȅ"0 | GJy0 Fja "y:gjwn*'Ei@EaM!=,diar,hiw27!s` 23a$L0  Om >)0GΙ/Qk4ߵ0;eoB.̀`L)0fCWͅz> ßw4c).Sάa>cv{SpEb⨲ʩZB.PZYYy[_@GA*i'_mXWs 0k\̎;_`n6_k1:rܸh`k89\,`_X K5\D8?'wG5l@o| `A5p$4C l WPI8Qˁ% je\P8hf/wÀ& aLA0[^IBX w$e"6'I쿓I/W2/vv ^/KrE^ B[^Kw\?:o7M{[6p ppށ##?2܀/A\[.eU*e1 0 Bg$6sS3;۳E(;P 'He2BqC=D(A0)_@4s1k0Vn*)16Rd [+Zi*kUKv&mU8GoJҕjk%ca$Da-9=orE%ٕdD bbʗU=CdR+_lU_d Ǥp;2_b"FJKX W*kq2R[O,*jb:"P#XN\Pj۫SR6evoٸJp/=v^XLJ(B=w=f[[voyT=\!X:Dea^TkEҺ6f0^^9"\lY * @^WypUFѕ 25yUmqUY~+GNeT)QڱJ;RMvF-,s99AޟG4 a!iFd?G@T&:҉UQ,y`*ֱR1\Jb5R8UT1.*k=J[x"ZHJ}Y%˿ZK8b:-:%[ / 55w4eQ#äXDc%US^kRZs ֑#Dޟ&pGHJH0u_Ϸݱ٥A`&SԿMɭjݿ>ZwRpZA:'# 2z?tΏ}D՛ DԀ9Fhd 6`cҞ̇;?Ry :v3GOwdffzƮpeeͤb++Y1RzLv! 5ּ)Ŝ׈{ʴ'3~G.qrr36"[Ӌ]U6;#\.*`7A\*ЂҲS XUJVG òZf 0 R*"Cir\Qn(wx) .Wbɬ+033lv\w~Y>w[2; 7+yE*t]x"IǸ=%zԛkA.6r:^<;vp(V0¸bbz1Gc?#]cOxqՏOO E/<h᭻z.c~ aZl&@$BxtQ:hq5os)GoL6+&KJ4B>dEtv8;Ln h70:]ov/:Q930Qau+py^朊tu0g*uwmτ* nww=+jJSOo +k9׼1 ּ>﷏Z8vQG.3zAI2A ‹ew/UobeN}e#f+,8-Ʒwf4f҅5ݿ6dmSO 'b݄&VG5;X-#23 .oe^56aLA}T1Q^ϒڀfE2@:]=&O[v-7s7Jm33x@ɽ=>.7"7+sɽ+6Lrmr7޸IyF<ص03z֖G|qvt>iSX@ XcQ VRU2jE&r!'Ǖ#2ܒU,WfB "W(uK}h!Ȱ-[l ~u~|cdDVݺ%Zbx4fωi8tsiu'ڑ̰#@lTea%cL/Co?^0fAΚSBl\]G:;qPRTOOAOYYV6r'WVMO?ӷht<+);%~X 05#{Cѐ mAj1=" RMySjr\Ƴ;t&I)Je"Qd߬w_5`XYo]fg2G͡Xxx%+&fd $㒫 Hkʮz?j<%4DQ ~T֔I7X70bNK71RCobbfQv@pF8޸>m mHL@߷zcu]5cZ{7(Z 6!u%Ə=&)o}er'E:2=$E6fLHߵI9cMk^hYT[cFpۍoPܿp ^f )~ܷI'&r-׫G3kF^nG:f&6C*T}ÎW3gsi>ueyeƴ{YkXK:bzAiЬ5'7֎Λ/4=)_j` X:R`$ il@֏mcS2ǎLamq}(A'VkSw/Jc}EھO(~oiG]m%L`r/\ҍp4n`+Z mi]F&#7cJePF_f $Mm`g ֕9>8okNeJI/m̲A ͙^#XHyԠFiʴ~њ=Fs~bK 穗rdSOJVɒcGhkSL刉qd%V IL꒕%)39Xf*C @N@4Zs/S/ƏZ1rV)DkO@C<+uF4=vh w쮬$ڲ7Ń~0|}3mo%O]K6cbfCl:|Mp=-Ƌ5о X%-xcD.BShU,(NGŹsN2-ݿ(.z|H۹:$v~h dB#E_R+{ gryaޝiwmҟ8. @:%qW{%;"v**֭4ɑh)I,^viΫlm3^wJWw3T8[uoȰmmQ'fؽlt|lO7U 7$}u.d/rf(NolJ-"@\YDTA CǛLw O|%k72c'{>L;aͽ <`:xӲwO,?J_＇KoWy}^e{ʈRF(9osZ=2VOpnX9|C2{@{ NkUKjA^ycԺNcid~C&ytvH Q;n]dŽK_wŞi2w>}e]2rʨxgE62Px)trorf1Q Am&̘j.EX/EիUly}wt^?+%3s/dC~H{--ݵǽMھ]z4J()Me-QnD诫 /O(;L裯a9Ij&ibw+וevPl9fY41q׍=7_|W` G2oMH,ȱe1&zz c:hi'*+ PCduȎժT8:^eGVW7<^7Ҽj3oO /o0a'ܔ1kޠD>Ǧ4BE6jq ĔDn|BhP=|v,Z\MҲ7i?2c<8u},<(^5=VFEУaU2R!u,gy!OfIK~ucײx(0b12@|x(``llBb?sTƏǠ1Ch9>|FW??|#Drj WNs x%NN')|x5x,{}[2a6.9P)M[Qb( niz}o)dx6̓-m ɤn}L2dO`6aRՃL2k@{W>u9A5Z:vTwϲ/1 7aɕy6ا*%ʾVݣV?PT@X`Tܤ?SqPqSWBT\QW**<_QAŗT|ATT|FşOT4#Q!*NR>Q.'xT(GxS8DśTATSK*vSNE"xTl*^%*^b/P<Q,[B3Tli*I*6RxǨxGXO:*R0khA*VQhb˩XF*b1XH|*bsME3hn*fR1TE4*R1*LETP1TLTTQQIX*PQAh*|TQQJE Ip*QQDETxȡb0pSџ~T">TȢ" *T-~ 0-P2A`V@|Ȭ'Y!~@";as?0YJm 0KBG2K`)D/70KY,]ȭ3BfQrӘE,FF"EH>v Lb``3`3:Q6J\yPFfXy9,\n&>bJzCE}P196YSLʚX;4i8fLzEENN/)EUT4cS1.bcQzaEAz~E^znݮ1gf0۳x.3 5Edܳ;_Vgx?`{ROπ : nl Ap'-Nޏ'* .\"HJ-7_\ y~ 3?|J g &8՞0 >"$x=w NCpQ#o-$xusy齷}{ &h'h# v$x`vW^&xEm/2RQ# Fx  #(&JPDPHP@OGK!!B0`@n1u׏/A6AW{Lihed 'AovsK#Hmv_/(iNIЃ AНNЍF`m7eOЕ X], q1fh(@'DA% TJG0HK4x[/o/a ^'n?Ubed ^;5xo ^k`1x/w/n ^/?5xO ^c?kg>ǟ?}GzA?zǿ} G}1?G>mǿ񞍇>ǿo}zP}~}kzO}߭zߦE]KW:~EWǿ_/m:]NW?-:~FWoOx?ӬOE6OF6#'" 㑍c#F~]d#68_?)qi"Ӕ4qėij|3.'+Y&R/hjDncZF?xc7݊ xȀk[.!=sHz֣Wľu0:W}^Q]:^U\D7 6dG&/5k )+&W[&Uyťxd4@R^Uj9sRS1yِlͳg776Ϟ='uvjYR͖f˻R6=7Ȱ 0   `'x ^^^߃AK E;o _AoAo@A _@ W `%9x3'Sc,x< ~~<  @ m [ a&:x< k >p/ m _wAW@A@Am s Vp   || |>n׃@ |\[@ rpY%! \+}/ 9!\!B.e\{?^ endstream endobj 346 0 obj <> endobj 347 0 obj <> /W [0 189 549.80469] /DW 0>> endobj 348 0 obj <> stream x]j0E -EJC`i jY_<&Ѕ$<.3B5Gt ֙t Xrcuz<9al\?\|`y1Lo.2޼\U73^;֍.ڸ.}F|-x=}!tnVJ)e˺늁3 ʺ U2R'DT߁tFRr40yJխj+D,RϞl)'$"!:u_![".:xO~Z/ endstream endobj 148 0 obj <> endobj 349 0 obj <> stream x͛ `U%IYH MaIB&@Y 4[: JXE(PG7.B%,6#̨}F@qFFt߮:]8o}ͽ:uԩ?Tuw`5xM}4'61~A'[3,r~Z8 FtM fΣK n̚MS 6Ϩ[=жy.0ϡ.pίטh؂E @JE 0P8C t`CS<VYW*tgt)|,|AXF3Él D>D"`0<-h\ԣ13jZaʥ"Cꞅx➡pXY @}Ǣh-‰B\8l,,BՈsG/]G MNfsA> 3SSZ];8u7ߌ /uMЄjm8MB#4d_Є)t B6 MxX> 0=[Tk/I]hn y ߶M8H&j(4' j&r^rG牖P˶[q+PehB p/12ƣ،m87)+js  }"TOulPSlhUpPmpwFa9?t'uG! _Tk< h4a.`j1 !a6``r|,r\p#nZ>4wF܂[qn7`-n܊;Nͫъ#.9fƽ؈ `=6.܍{܋.?ԜLX}-Q<'4E~Ny[x[Ԕm8cDq )yi$ h,j1X국T`fJZMX-pZxXݸ_?i~}u.G׿b dt`vb7Vlvt`'va+x*"bdGRs?yɾ^xB'$N[|38 .^S&SwJ%y)_3G{5[܏]!YLתɍߡ3|2qsoC>K?G>QH h|OrjMu@ŤƏS>W0j503_hYq1F^'!]Vd!]^lrZ% u)2S9W.c9}s9#23n| ԊjS]O>^u!M0k\ 4eVS:g\dV[i]Ifc33W.̀Ͻ"U~9ieSZ/ɓ*KK.Wb,Y_,Բ:6g{Ɓۃ64ԥ$T_[-5m|i[-=]._yJfFi.)%ζ S_GSPTċ$S Ų^>KmA23\jDS$U){Vk{.^v)*[2+E^̐4GmLmCefP]VvڜemꆶvmAiݬaJ1RzCZz:TrQfF;v7hʩ{ls⺢>z𩩜$*NeC))P=>`WPAf3KiifSӔ%34eۯ̵NI͊Ymu5B7Ȝdr̹G7ɱ"9](,]E2u 2!չ23dbWtծÎS5.Y突rLzSyʂgJ=PUkQ#/(=cO-A6xcWM[Uy K^]#פ+']er0Yԥ)'ʪiwSc=(QYRrRHpzό:̨vE'XKiFrY'+ J TƣcaWnfc<69#Ǥ]ҔdGQ"=ȱjփJ1AʤZAfϘzyu;>Nj ".Z!jP#eK rgP:&{j.OL0^jVڌ|k/"DgLj@aȴ4hfaxr!|0 y֯=VgRwbt}vAǧNQG;mg^gu|3'.Jpn77o@.򼹽8햤  c.Y4\ w9'ǜ쌏-dQ8qPh80ufUa߇/ܘYuHފ]x=| ), :L~{zyL =5&'|S NxiJ-ew9{BjC+C_SRAs6Ͻ^eStˡXw! |cs@DH'|1 =W(|AvpgNv{...nq~%L䡬= Iv>3ٻUfUn;,ѕb-iJ޸9FU-) 6 OBr)3d\-rgh%WJƍJ4[ç|Nd3)) fW d"'zS=IA|1zL8+fg5->Pg=?+'B;NyܽQBIv%%⼹!Դ)Mt݅vULmȽ?*>"5oRQ1~:)9>_`qzySLtH@r}Fvlƾ&].뤘uxO'񣝶CFR]àR_?WjšWn3irCuFGr1sG̫+_uLonlh\7yI9#BjVR1Ê =סe R/f?MB -HRXKd{6yXSڵڬ[K֍; y kGR^tFN܏KޢݻNel+A׊D0t#)H;|v6u)lJ$%jkN=`]jΞAgL񊌎H\ꭣMfz4\{ǒE^bRP髋çz?|;L$i1|II}d>f2VT}ԩvPJ\JFqCʆap4wUuKFunޥ#?=w]X*ʟ^2@ǥ{rmz`ƬK^z9/\@q̌I ~ H@" u u8LI8hM8}rl rYμMiީJ<+7ǭ3`=ӖYןB,kiCJEUkzVHCqBm\2|}+\?+r}J0m >eq0ʨXf<谉oTpP\@~V4|)צ\ΣYYY|ۙWm6FыCBIݒuom w\IĂ7(':%1[z6\Q0ߙc2W]l랙[2GZi䀄Ԥ=%=hnMהfιSb&f6xšZ#gr}G_{ྥW叙5IN.5y>WNk0]L鼘=i1a>'(nWuHAV5NLmY;4RWo\6oveU):wnIۮp,ݶM@ƽrk$dMդk |8x@sAp/& J]}sP~D-<?QpSjP+u+<ݕs%(S%'t6}HHcGzcZ|>}3 IAbY~4h7ȟ֎vڕ~=~NckSf/.3*0!@)+Mȝ}eI7_;|݃ k$7jɅ{Y7wQRH;- M7HLHtg9/V =.k-`0&[)M8#uy=|:7S/9fcl1N*8WEnWY*OݳޔC ^{|k.&Ĝl|_ C77n;w|(:?y!mjOvMJ/[+-|:4w{qw[ޮ@)+9}BP,u[7&#Ou sRG.ua[A:%eG§Qnurau'i@G@lcYgfgG+нsȀCmwv/OQk4w#ݞa(=VRH8=2GvP88ݛmv 2;t<<{ҠdOzB< Os;u 2}1t#@6e wjMM8IIlG>II}u $qh9}@tG`FriXn$t}3id$Un#e]wr˗ =MS.ohJ7S~p@ĖBOGfGnlv1:Winc*A08{u7-߳G`ԑOB%Ym6`+4sӼѧUWyNͽ(d;~N{rxqhr~MI&7NP_y^] ^ޛ潮/? {'z"BpSsh{@odT8x(HLzA0.dywVCqXh|"ćn -[ҭt,46n߄V>~5:hTqeE(_ٕϰС[]@hb({uqu}2}>4|<}$;zttz'xv:sP_:2U7s5w|:`3&: iPX&]&?i&&?h7M;M&497E?k&_i&_h&i&M>#M5&j{M>&49MM&oi&oh&i&h&4yIirPEM^yMiW=5yNݚd&;4Ф]Yᖁ÷ܵ Wߛw--ElR8B*Bq>W(ΜU531SPU[WUWP];J*`ꉩܔ̪*YYUPI*_ jRĪ)k"=RN @952KJ22 |An~Gl7#WiG}\ >9C|A w-9:RA*(bbpgs ?1w ?0Ñ% 3a[ N2|?3|× _0|ç=Ad8 1 ` 0g8p p]wf8Û o0ë 0p%1d8EgǰaC#PT~}QaN  2vm 2lexidxqe- e 1<&62p/oa. 1p 1u$t+Z[nfheF0fXp=J cXp-R% 10,daC3|y sf0aL&FaCC=CU 12\0[Ud]0a2C%CaD 12a(gPPPPPPc(`0apa C;"o`nn3707[ o fsA| >dn47 bvLfqY,kjcj15wŻLS,35wƵwĵǵ܂sY))Sx19+ $y{2Kve W'x"QX@m a. 6w+:#~eoyYF/_aAAC8iT}SeZUSn'ɲ]Hu;ZS+;͛Sjj}>ÊE5-,NOoiiŋZZ!YՖEZZ[-Z(e]-^uYl-R7-P^08G8@0$ A.HtD?A!!YH$$+$DAo!iHt D@@?C!WKH$}>D$} >DDDDBC qHt DC H.$z C ћ H:$z  ^D/CC%H;HtD!ыH<$B=(D!.HDɐh;$zmD@!SIH$z=D[ o!fH$z=D h#$ ~DwC HDwB; Q$D@!Q+$ D*#] V*#^/DxI$"mDwa$͑ΏDu^$s#Q:9ΎDuV$3#QmD1U)6DZj]$WE:=iFze$5VG"zE$S"Dtr$H4+"ќH4'D9>ű(D,H #E"VHGHD48HED)7H#QʂD!FbwWmIv+ endstream endobj 350 0 obj <> endobj 351 0 obj <> /W [0 213 549.80469] /DW 0>> endobj 352 0 obj <> stream x]j@lhP0zBe,')t͹de^JLMEVvn -4$/ZlމXʼ-Rwc)OŚ|IBἛ̠{rΪp> endobj 353 0 obj <> stream x xE=wABB +I&&9:H$ܨ뭰*p8 ^DcW@pE 3)y$tUuwU;$0c5xUTgy{@]Vn? K?)}y<37ϮokE2NΞ@z sů_ u̙Td$s/ZӨ:ྜྷXυL 7ϯ_jC/2M֖E }օM}C m( 䶿zQ 58X&)-x7'3U͡wBWTs4]_eNS2~4Hd NW]y\L^L6A A %9\Fq*SejرM;X$g3ɩF +xp#՘h2l 3zB9-)O/i1UJ/qZ:3DG.FF\+#F%}2m,Pj|dÎ",\̃;r!(VʴP6L\4b!Zf,pVjF|hl,Vr⩫9`k-DǢH-3aG!aa.fcM9jBҢ%hLVO|}H%yFqsNjz]Wר?Lߨ0 Mhuh<:L ̄<%o@a cV&,R͸6W+K#bn6Nl܂vzIQ)+_)gt\sf܍{q?xwn܃_^w5alMkD`P'qo.5^ ]41⬙3OZ믙T8aw1e%EѣF?l萼̌)~BBj1E:F9RgY]JT) YoRIve${R㒞zZs$GbdFiN82KJvW(gÑn&)K^*-QZWN: &CF:: Q⨌tHdh7tx'IĻJE_Zp*i(V%i%r-\θޙ~W+ҌSڌcdKR%Rꊿ&d6IΒR)Y].$RiX䪔1@XAciVơ1i%M2K8Z[jX;VY%q.s8GC✣; 1JgS, ӵ""vyAs6dKZIC^= M;N$uHtIivI'\c:I#n|5V]q>rI*SΑ"jIz$VMo[erpIBNoUU&%\d]$TiJSK;IkԮFq5{BcYH I4/RoCR$rxW 3%|M٣2vikki啣ue\>嚮 \Rk\IZ'GTs.ңʕ%\c (rc'"*r4U++IlN L$CR {^}vמ(%(yLAt~~ϻigݣ'&Kܹr2&.lCmgϚ{p#V^Y7bؒ*&8&'wOv[KۦMjgrr}6(R} kL۩no|?+>wGتLu#Wp^}l?z\p偦[X;3/.jdwl|J x4 d >@5ޣ_e!* g[Ir%'glǠ4rRuGgqh~tSw>2}+7..}W' )0_ v(y(ddž~::UeSWWz/E>';&R挌>6eH/[%{FƮ5cn|Js ^}1Fyk.5r%cš9>Hgٷ[KUȳA‰*R VbGg(vneX!Wm474U:C"q\Om~>fwݚKG-~zm-{y{X?dKszqѢۻȊ8h3ʌb晴ԛXtuI2GEe3/DYt:!2 I*UEg1oDg=RN6IqK&8is9xJ+w'dۜ/4g('`X>:lxfҁTL *H4ΔԜ)SrRyGA:J0Iq[ceety2]~Ȉ+6>q@n@~V |*7YYY|cn%q)h&q}!C3yGh peUQS%|[!) 1cGw4Vؾ dLbJqԠ丨ٛD2gm }KC}xEડɌL!Lw'Rr93stiCm쟖_8/;>="E.iy6oNcpנ4^Ȯ&8GN$Sf+W#Y(y2dBQq*c'iYyr*k99h{NMjE/Ǹ5b*G4ۃ)l[#Bz*1뉞5ھ*m!@z kly,+Pp棴3JPOȡv+nGs9b%4|OҮ|@ƍJuŹr#ojĥ$MK퓜_;_-R/R/W+C\[koq cLTF> w&'ȮD ]x)3KsaPe̅~ɮĤ*@t~>$?|nIy tخ>1ת;E&<%o@}֒`vlm% ѿjRBfg[Y#!=+cO-Yɟ>_]<჈GV'K;ǎ1>C|UT(m6vEv 6WKhN ;=蹁[:azE,a`-΋j]>xFz).2yUn}icW[8R+I_cB-oZ| kqnjQBM _⃈ v vXC YΔbLV+5ηi E):%F0]gnEynAu [9m/-2շ=9g@ )}E$tzXΦ!xY'?~@ua{eÿH|uswRğ}ݫ.=t򨞕:C~{'7 @8bݻ t jaKԮ(.|Q^K~x=mg J: w"aҗhj|ӲܹJ&euوM}w)]1A&f5GnXR6`PRlg89d}(6&֙_[ZExuZMeju]OT <oUʫVJ W[57> 齓֚pb"Cwy[  19U+,>eia.(f^5UU=s}T6ELV(Ad4tXNz Л=Ui4jy`f͐׳Ynwb‰&΢c~{(etϜmOp\ P)Vi4Fc`Tf*XhM*ULYe7:[,S0Ny⣬F͠ҚLZBHURϊ&onV2mn[tms'X&Ĝl;Z&;U]ooNvqbӓ DXX`g`qnnRʻct~.-nkw/=?R<5\I6ǂ;Y_xpOb{iYtˑ;Qn=uwkA /x<eԜQ*@5I$" *?wwdR|L^a|C&a?3yɟ]&09m&d7LN0ykL^e grKL2yar!&/0ysL29d?gc&t1d"1&;lg4aL2$`&n&Lrd3b[¡mv\;w+Dn-j&YZpk[+4w ),n]Hnjܪٕ*VFέ[Vnx.&Us+DR݈FpEn܍ʹ7`s+askn6)eoR-[Y-$B _(, sjfg44e5 5u5Yuuܬܙ5CS֩r3jj jȤꚂjrlQ|U55$l)'p9i)'rRQZSQ\SQX p <\WCzcٛ6xv -8շ8 ҕ+q (>CP|@g)DŻPx!@HśxQJ )QDqES8Lq)8Hqb?E+P`^=)(:)$];)Ai(SxXgWxd Y»'4>f'i 07>'n }«f'l >'d G>EO'1>'` ϛ}sfp}~O}³f}Om ]fij$S 45ϘaRx H>H!SGɇ_  ?C$C$HރHޅHށHNB$oC$HނHބHH^H^H^H^H^HC$ ɋ!#aDDd/D" tA$HHv@$!! '!A$O@$C$A$ @$[!-#CɃ}ɽɯ!{ ! &d#Dr'D"HnHC$ vd-Dr+D&UMɍ~e8^p(ݶptpT燣:/Q.չ Guv86*jC8օ:+ՙGuz8 GpD'#Zp4}hVYfE8ќpdžWXQ8by+GkT8R#QGiX8JCQR^8JQrRN8J(eA$s߱+%ZRf endstream endobj 354 0 obj <> endobj 355 0 obj <> /W [0 189 549.80469] /DW 0>> endobj 356 0 obj <> stream x]Qn {LbYJ,ЇlXH5FRݙ]; JK˼Z4IRJ :C(ov[NfRG8*[Vw mWc~pB퀑3o݄@HNtk3iI|%.h;=")c$zU ;Y c)+=Jd]b&vf<> endobj 357 0 obj <> stream x͛ |Ugfr5Ii)mIBJ!@۴ eZ@VE VPW*XV+u]  4y3s2軟;sΜ<<6) a)P_Vu2P?mvCkQΗSxyϊ [tTZ!pg-lp;A>8 gX93f45h&g̞{e˳Z5=l \ 2a-ms?:#ķij˥YԠ(PB`dP 2.hКPbj^b { 2͡Sk̭H|40`8zaJRu7:cn J"wL3(eOǡU$;1f/l6EEIdVf; Z``0@ i0Fh(J6C!1$i2!J`44&9<`2<zGigDj/clMR$ZF,h! FD4FHh]O/'@́6 -p; 20f, 9P(i `&L9"5\_² 2 a3^3lk 07b A>̂Y`?̄0BxmbCp0HEMY ("gM#=;N&ͼ*˚d/w)d&FJr2ҫѪjPSRyv,.nu&r*~EѮG ~bo0R_N}z4/+C쀝^ C]^H/ 5!{5S ;ݑkru^nxQx)›? C .oc聳|_9E\ \Ct4c<&_Q.CoPq}sPuPPx37eZf ]JnaCa"4xGqLR7yRmMuUl1KG{F>3tHNkPzڀ$gG?6b2tJBH+vzIr ׎pC@=ok%?Od6RzIJhib?VpREƯ.r'j&I9j48nFz[1_2FGq}Qzvjԅ&uzt5BMz8`$P<NZv7p|yEMqnàP̋ 1/Lfx֙vSkc%oJSE|]KO+nE|(=˜F{qC"!r{PcWr|v`/45.Rky^9$DW 1K;삫#34I_Nq;mǒ$>ğ%$$$qZ$qR'$GI$ޓ1I+w$$ޒě8*#xCݒx]aIAI~I&}+=HUI.IItIS$Kw*W$$^ċxA[$$fI<+M(g$$ēxB%$o$$ÒX'X#$Z_$RI]+$\$DHnI,"I,ĝX +6ȊD$nlI̒mU3%1C%,&Ip&FI4H^Hb$HN%Q+ILITKJ~ITH\e/q#ђ(D$%D$r%1\I IH"[%D$2%! $D>vQ+ާVZ- NF Ou/l S¡'8jIrj ,ZuOW~C-wq!?Z ybh?mçbŀp u|JB-O@7ԝVl?'58jTZ6jw5:ggϨ\ݔUOKonȪvSdMf'DN:3^]WUyx7/zEuyzYukpc)Rl)Eo)WVW{]*Cju[W PסCT}T x;vd);Kշ(J(! A/5]}R^!\&. ?%Dp  |Mw|E%g J9g] C! B >$ N$8?  OKoIp0!F`/@W\>W v"I'Nw[ ^!x% ^ B `$A.<CoAA6`wWtyed  .KpK#Hr@.0& H&H"p'p#غL%H2_+AAVx >c|Ub?|Ol|wc/|Ec/|y=g_| >o~i_|Y~n|lǞ1O >cb| >C~` >Ϟz?G=~==;z?ϾoQ=olϾz?]Hgݯ>ݫ{~6nݥ;~vvluv]#MNn5ٗuKFE]#ݢkd5ͺFY]#In5t3Fi]# Pm:;}B®׶k[Ǵ-o-m ]maj[5!MZ>` ؚ4j_Oh6KoKyclIe} 4 71:ØQ:lV4Fv=]POAGQy T_@xedWJ[1zNćj;*M®xݾz5$ʚ.zӦĂZT^CH,Mm;m^jj[[͛6R??mRS"mܶԶsMm{=*M\RHܖ ~}~((0^*px888'px888p-px 8~^ïÿ??{3'_Ï??OÓ q}{1]m-M(px8|8_~5pp8W.p'p8;C88  n7Í3Szq17#:p-p8|8\ vÕ}a;p8\. wIؿ{7p8_\° {xAޝn[ػs^m {Wg:+^5ՙa{uzثa6ʅ:-ưW^{W:%պW'=ZhMأhuأUaoެ{<Ͳ7LJ9.1a/{$챂=VnS^44!a/儽గa/eRFK.pp8jqф]2zhP PDWA' J@t{ [o4"A8o0q1,Oz:{N/1y\=o@$-zʡp$R1۝՗¬h! *{H_C2m 'vۼO4eL]lfcXVfrVf4^@}^RsWL팤3mqz L P5iFȔl J ۇi| (Qe2 2vWqM1{]Yreݽ#̰;h;@wO=ScL ~.^{[,z & )P9]:Z->5S"?sy!k݃'{LcFfXvf}iZq;k$%+ qWӜ[J~7y|+wڨԁm_{1\9u7Xf Nu;`opzBNEwYCGEsY*;}D]cwQo؇QQIA^yG a;+&6z:hٝ3OZ?73wQâgm{rJ `C%1z *V)(y_j3LgB#ӗ0v{23nGM{~ak~ӻWf;Y:@bf%v{Ug0ng4J*O0t,|TҾ!&{ݤn!T}aglnѼ%*--Lej}<^1g;j6f'Yy+JZZU_ls P5-CvJ(h䚳B|NCYtqP#Bأv0xO`o1ikQB&-6՛*li@`Ș8EUy П`hB+k&6_ Fg^93T8&3zr]nw\wGrqƈN֠#;$doK^eb_=C|HгkʬA˖-xNh' 2+2F2|ki5V*xv-v填Փex#GɍQ/~\~x- 彳SekׂװM< KQ _}9Z= oW2ɈM%JUG0*nl:r[4¿[1~ĪkB]eIc|^OmCx/[s?⁽Fx}VPҙ w$E$y_G.tk{:UȐoKݗ"]]m+ώ]um[-pcxg}\8'KX )NU[جc3}3V+i\Wnm=vD8% 2+(!C14*&rJHB>'x0e33T@7Z`0܏V2][ "E.Ї *Ru52 a~ R^cByeO =ǕaO3'9#iMO gd/MpW/ϙW|bRc䇛r?uDywЈ&(M7#WjjoKr<5kWŷ2 &fč. 6! S^EUN(e~sTqN2dۤyUHc/=vmJ+Ic/]1}kƈٕ7)\tVL͎ά&>B[+C +x`QSTښ Wh?90 u 7A1bn-Z3B04澽W_YZ`gFt&#ÂwbcwـBk0S^SdqW~M^V._=̌-&iC=&.Y%cJ_6aĴ H~h#,=z(\YtEw̟D1h^}+6{Uot@f` SZepaRE DKmtqENEۺ9ﳍQlOgE Ԣ2*ՙ A_~[*X;aKyzZyk!du)5bzeA4uTICG#qbdL.ّ^Ka=3M̻0z*}K&-ܻWn*L_W,JY+*(M^Ʃm2W IHOuLmb(5;udᝓsoݭퟚ?+#6=t4*of=wL305f3ʇ ?|0o!\0rip׀xFv5\_m4n&a)8vh趉܂m)eeǞmrmo,h~5:.[*H vz*TJ˨.+*U[FK 'D\merS}crά麵מ_NI}$f&E˃u :V{ Q*-Mv ?'Ĉ&mQ߃d"Mh<}cb)вl=o.1=(s Z(&4ìq[ fdT@ $A {@vT>h.LxkDF* U2Oc=yOqVWv~F72Ӷm׿P _گ=3!z>.k(4E|} J]wkj -t(L䚠CNM{cuA.Q':e :՚=2,usxR7볬F% YGzkKv6* q&-9þ]9xxAށ}\Nm~"$eE[[>)7:b ic(T*ʅ$uR':2 oS4?j&r elm\bA ֿ;tG!*@eoaR8"@_?)Ma+WPUolP i)s!q&=C$Y,.gؾ4HFW+m3*k䢶䩛v!qўf]chήWolO(ʳ&Z%S )KZRR<%5BIBo!;:gǨ eA0S֕Xtd>&#'JIq"4}k=mz05cHAJ'}-YB ] ;)ztݫWR]-3\QšE=d@q$ I&B6*ѧOmض͖[8.c9w|*ϥvLD(56Uh*ZeBr=C/v,Kh^=: \7s36of'S Zo˵ZBhTJM&#P`4Ac(΀)t 3 jZI(t:JY&WTPXa ō#ڏ0Mfm/a"{ aA` >.u/WStx5 ><+H띰_ -IρNt:W޾es hFR {e DB=.HH_B6XZQ);hL]6޽R] CT2!(TS i iDR_>Q57ږ *t7w=\)* ]7(+<;VWiV~^&C&}v(Ut:#;¾Xdf`$KvMvw> endobj 359 0 obj <> /W [0 189 549.80469] /DW 0>> endobj 360 0 obj <> stream x]n0 yCX[$DHGc} 4 遷V!D؟GUQYp<ޜ~X(_=4yUal7$\|Bof [&] ؞o.yeM `=,My k35p]Ղ/K^?3 Bȍ[Fkl,Rʔ'eY)Ǥvq> endobj 361 0 obj <> stream xy|Es䜃lua!@@ "LN#B&Dg0dR Ad"(QA0.^}P/`EDuPQw]YȼLxy?$SXP[4ds;4a F6iW?z)`knv[| p~doC_x6cn5`C-M bs=?X)--M 9Yzl$Z.h݀r`FkcK.6Gmp:Ⴆc (C65= F۬_nw d# # ƽ? (Bͣ ?M6Y٘YSES]#4;k[80zPb +}ԫb֤R 6, N5um- mD˛hVسjQأ;VU5t_"ܲ1iY槝V@i`F 7 nCv~0 qLG+fB D AEfc:f@w=G+fqt4bZZ31F0oaBh46{f#=ál4, hOr Tbf@E1 -hGl5!n4A`?_k-XNdc07V%.G ]vgx cX`8*nwWd)uIw} Vч?:+)Ê>N{|=Nś=xȰ6xȯ6caCG)VqarZ6*쳖W5 N;zyyً_f,6G ctЌ8:`dl0Ը#ۤ25qZNk5ajyD4%jl==QoUe45SӬJoYEc-:oZB {TTlj,:؆Vmzzh@&L Ozk6Ҋ*+u Z1&ũ]CUϺb EXv\yX fG=BSjؓ"kxM#%[ÓoYV_OFƝg2հD4OҬ>oH-4-r6`Gza?,jbZ^ɏI2˭&4m,hZTq4-lN؋5/ӈZvY|fej,)V5LT&oۢjaތ6 z5fwɤiJVU1fH'ceڙ v3{BM `i~c7_ȪUQoUWuU TG+l0HPƥdIe.e]^+NopI”hY$&AfU1FhFØ)N(xφaZ͂nL2LYchL*Ts˚Ƥjf-ޠY[ #hxp44Mb=W6i92>ڨݨgx4vRgj0<އcJ5JM zֲ "fӬ1wTh :P6mhG&쾱Z^JϠes"HTѓuDHq^vkhN[?BE<lbYqjThYr"Iƨ!+klUjš_Iw¸-/Ǒe 29 h<6_F$B7[,[iY ZO5֢}lsfc$Bދ4f9S ZGѲ}L"'=fwY|{s:^w  HO 9̟Vf3'~e:(+UƩIE¤ -,%[a) {)IRW)HZ~)=RvKR_YR>]R>򉔏씲Cv)IPʟ| Rޗ)IyW6)Hy[[Rޔץ&U)HyYKR^U R-R{)lQ3R')JGRr;ZmRnrRMRVHQ RK^uRIV5RJr%RKR") \!2) \*)̓2WER.2GJYRZ̔rRΗrRZL,I(%&AJTT)S+^9R"RRΖr:)H(e32NX)URʤJ H-t)I)2\ʩRN2LP)RH,e")Rzr%uLBY:,CBU?T.>Hkˡ`bآxU: P?V ,@咄(K*&JS|2OUZhe>Zkخ7ϝخ\ Sخ̅E`XfnU\: *f+X)oJ)ookFaH(::L2O8Yicrnt䯭]6ղW_S7?m+VWjV@5WUu23ڠPO ၤrNmReVC@ͺVo'W%KW'XoT`݄ÄC x@oo Mxx}Caa7K_&|AaS'}$IAN!O$O=»mwo'?'[7 o^'Fx eK [ /'_ʗks[59|iN'mN'wam}:(mw{Bo Ukt/^k{)^^ֳ=wvָY2ipPU2)u\l]\\봬unt*;;-稲*`l&PP˜xƖhZ5P3Y/P7pcDR>Ia^t)e͚eax `zpoY >;> x^́xZx{{<^Poo]^o?U7zͣhMcp ƿח @( BKAnv`?@!wo}`!>}@Kg}vAO!'c`!GC'#{ޅ` ;m{^`AW!+e{m`/@!sl {m` F {=`O@ , `AG!z% X Z0{=`C ؽv7 `k jvn` Jv[n`7@zv[`@]@J-`W@|^{ _j'|zsttzT[Tg^:CO|=T멶NSmSmSzz1==ըT=)z멞' 뉞'zh$=͐fD= zgiS8VOJOLOTO,'6ZOt=J)t0=zJzJC) S*`!uO?;zL endstream endobj 362 0 obj <> endobj 363 0 obj <> /W [0 189 549.80469] /DW 0>> endobj 364 0 obj <> stream x]n <wн.ƄC}ђԁ |Fؤ |sE.Do:L08gD%Xg^L:0.UӭsIYUOݜ 7{<3~NOٝ~pBJ X]ŁqÇx]EJ.5 .^n8m0jUBQCնm[3$|k ~PЛحǵW{fYbDJ9{sXj[#d| endstream endobj 152 0 obj <> endobj xref 0 365 0000000000 65535 f 0000000015 00000 n 0000716786 00000 n 0000000310 00000 n 0000739552 00000 n 0000742650 00000 n 0000745717 00000 n 0000750159 00000 n 0000753781 00000 n 0000759791 00000 n 0000766575 00000 n 0000768828 00000 n 0000000347 00000 n 0000773430 00000 n 0000780751 00000 n 0000792659 00000 n 0000796848 00000 n 0000800453 00000 n 0000000427 00000 n 0000000505 00000 n 0000000952 00000 n 0000001819 00000 n 0000000583 00000 n 0000002238 00000 n 0000717201 00000 n 0000006208 00000 n 0000021759 00000 n 0000024763 00000 n 0000030521 00000 n 0000032762 00000 n 0000717519 00000 n 0000805178 00000 n 0000812806 00000 n 0000036577 00000 n 0000036225 00000 n 0000087147 00000 n 0000087340 00000 n 0000087625 00000 n 0000087812 00000 n 0000717892 00000 n 0000092125 00000 n 0000099795 00000 n 0000102558 00000 n 0000104217 00000 n 0000114562 00000 n 0000116912 00000 n 0000117099 00000 n 0000718275 00000 n 0000819314 00000 n 0000120105 00000 n 0000132745 00000 n 0000136818 00000 n 0000137033 00000 n 0000137315 00000 n 0000137591 00000 n 0000137792 00000 n 0000138175 00000 n 0000138564 00000 n 0000138828 00000 n 0000718700 00000 n 0000143270 00000 n 0000151284 00000 n 0000153775 00000 n 0000163280 00000 n 0000166687 00000 n 0000719030 00000 n 0000170159 00000 n 0000179576 00000 n 0000182917 00000 n 0000192514 00000 n 0000196125 00000 n 0000719372 00000 n 0000828369 00000 n 0000198595 00000 n 0000198834 00000 n 0000199068 00000 n 0000719738 00000 n 0000201973 00000 n 0000213033 00000 n 0000225701 00000 n 0000720056 00000 n 0000229220 00000 n 0000243782 00000 n 0000250749 00000 n 0000270762 00000 n 0000282857 00000 n 0000720362 00000 n 0000284937 00000 n 0000289388 00000 n 0000292362 00000 n 0000297009 00000 n 0000300612 00000 n 0000720669 00000 n 0000831299 00000 n 0000302983 00000 n 0000720976 00000 n 0000306561 00000 n 0000390351 00000 n 0000721271 00000 n 0000833422 00000 n 0000393073 00000 n 0000414491 00000 n 0000422166 00000 n 0000422402 00000 n 0000721647 00000 n 0000425883 00000 n 0000721956 00000 n 0000429661 00000 n 0000439795 00000 n 0000442070 00000 n 0000455660 00000 n 0000457912 00000 n 0000469806 00000 n 0000472072 00000 n 0000481565 00000 n 0000485890 00000 n 0000500144 00000 n 0000503185 00000 n 0000722323 00000 n 0000506085 00000 n 0000515610 00000 n 0000518098 00000 n 0000528407 00000 n 0000531142 00000 n 0000722636 00000 n 0000533892 00000 n 0000551401 00000 n 0000557672 00000 n 0000568529 00000 n 0000573506 00000 n 0000722949 00000 n 0000576027 00000 n 0000592135 00000 n 0000597806 00000 n 0000612883 00000 n 0000616214 00000 n 0000620298 00000 n 0000621821 00000 n 0000723276 00000 n 0000624356 00000 n 0000627126 00000 n 0000661835 00000 n 0000674138 00000 n 0000693790 00000 n 0000701404 00000 n 0000723603 00000 n 0000842139 00000 n 0000850589 00000 n 0000861989 00000 n 0000872811 00000 n 0000883103 00000 n 0000895449 00000 n 0000902258 00000 n 0000703746 00000 n 0000703967 00000 n 0000704196 00000 n 0000724036 00000 n 0000708370 00000 n 0000724429 00000 n 0000713021 00000 n 0000724774 00000 n 0000724896 00000 n 0000725021 00000 n 0000725144 00000 n 0000725220 00000 n 0000732371 00000 n 0000731135 00000 n 0000730882 00000 n 0000725343 00000 n 0000725264 00000 n 0000725492 00000 n 0000725412 00000 n 0000726031 00000 n 0000725561 00000 n 0000725944 00000 n 0000725641 00000 n 0000725742 00000 n 0000725843 00000 n 0000726360 00000 n 0000726110 00000 n 0000726291 00000 n 0000726190 00000 n 0000727345 00000 n 0000726439 00000 n 0000727226 00000 n 0000726519 00000 n 0000726620 00000 n 0000726721 00000 n 0000726822 00000 n 0000726923 00000 n 0000727024 00000 n 0000727125 00000 n 0000727504 00000 n 0000727424 00000 n 0000727653 00000 n 0000727573 00000 n 0000728083 00000 n 0000727722 00000 n 0000728004 00000 n 0000727802 00000 n 0000727903 00000 n 0000728242 00000 n 0000728162 00000 n 0000728391 00000 n 0000728311 00000 n 0000728540 00000 n 0000728460 00000 n 0000728689 00000 n 0000728609 00000 n 0000728838 00000 n 0000728758 00000 n 0000729158 00000 n 0000728907 00000 n 0000729089 00000 n 0000728987 00000 n 0000729318 00000 n 0000729237 00000 n 0000729468 00000 n 0000729387 00000 n 0000729618 00000 n 0000729537 00000 n 0000729768 00000 n 0000729687 00000 n 0000729918 00000 n 0000729837 00000 n 0000730068 00000 n 0000729987 00000 n 0000730503 00000 n 0000730137 00000 n 0000730424 00000 n 0000730218 00000 n 0000730321 00000 n 0000730663 00000 n 0000730582 00000 n 0000730813 00000 n 0000730732 00000 n 0000731220 00000 n 0000731247 00000 n 0000731274 00000 n 0000731301 00000 n 0000731328 00000 n 0000731355 00000 n 0000731382 00000 n 0000731409 00000 n 0000731436 00000 n 0000731463 00000 n 0000731490 00000 n 0000731517 00000 n 0000731544 00000 n 0000731571 00000 n 0000731598 00000 n 0000731625 00000 n 0000731652 00000 n 0000731679 00000 n 0000731706 00000 n 0000731733 00000 n 0000731760 00000 n 0000731787 00000 n 0000731814 00000 n 0000731841 00000 n 0000732467 00000 n 0000732681 00000 n 0000738614 00000 n 0000738865 00000 n 0000739210 00000 n 0000739700 00000 n 0000741839 00000 n 0000742049 00000 n 0000742272 00000 n 0000742805 00000 n 0000744927 00000 n 0000745137 00000 n 0000745360 00000 n 0000745872 00000 n 0000749321 00000 n 0000749531 00000 n 0000749754 00000 n 0000750314 00000 n 0000752961 00000 n 0000753168 00000 n 0000753388 00000 n 0000753933 00000 n 0000758840 00000 n 0000759088 00000 n 0000759444 00000 n 0000759936 00000 n 0000765519 00000 n 0000765770 00000 n 0000766204 00000 n 0000766724 00000 n 0000768066 00000 n 0000768276 00000 n 0000768499 00000 n 0000768984 00000 n 0000772599 00000 n 0000772809 00000 n 0000773032 00000 n 0000773586 00000 n 0000779845 00000 n 0000780055 00000 n 0000780278 00000 n 0000780907 00000 n 0000791784 00000 n 0000792028 00000 n 0000792257 00000 n 0000792802 00000 n 0000796037 00000 n 0000796249 00000 n 0000796471 00000 n 0000797003 00000 n 0000799581 00000 n 0000799836 00000 n 0000800074 00000 n 0000800606 00000 n 0000804338 00000 n 0000804548 00000 n 0000804771 00000 n 0000805334 00000 n 0000811993 00000 n 0000812236 00000 n 0000812482 00000 n 0000812948 00000 n 0000818252 00000 n 0000818504 00000 n 0000818939 00000 n 0000819462 00000 n 0000827504 00000 n 0000827748 00000 n 0000827977 00000 n 0000828512 00000 n 0000830515 00000 n 0000830722 00000 n 0000830942 00000 n 0000831452 00000 n 0000832659 00000 n 0000832875 00000 n 0000833101 00000 n 0000833581 00000 n 0000841245 00000 n 0000841494 00000 n 0000841728 00000 n 0000842288 00000 n 0000849759 00000 n 0000850003 00000 n 0000850231 00000 n 0000850733 00000 n 0000861138 00000 n 0000861382 00000 n 0000861611 00000 n 0000862133 00000 n 0000871905 00000 n 0000872149 00000 n 0000872378 00000 n 0000872955 00000 n 0000882274 00000 n 0000882518 00000 n 0000882747 00000 n 0000883247 00000 n 0000894566 00000 n 0000894810 00000 n 0000895039 00000 n 0000895593 00000 n 0000901470 00000 n 0000901714 00000 n 0000901943 00000 n trailer <> startxref 902402 %%EOF flaky_tests.txt000066400000000000000000000010041524103652300141430ustar00rootroot00000000000000AllowedShapeTests/S2ClosestEdgeQueryShapeTest\.(CircleEdges|FractalEdges|PointCloudEdges|ConservativeCellDistanceIsUsed)/(-1|0) CompareEdgeDistance\.Consistency GetSignedArea\.ErrorAccumulation IntLatLngSnapFunction\.SnapPoint S2Cell\.GetDistanceToEdge S2CellId\.MaximumTile S2ClosestEdgeQuery\.IsConservativeDistanceLessOrEqual S2ConvexHullQuery\.PointsInsideHull S2FurthestEdgeQuery\.PointCloudEdges S2LatLngRect\.GetCentroid S2PaddedCell\.ShrinkToFit S2Polygon\.TestApproxContainsAndDisjoint SignTest\.StressTest pyproject.toml000066400000000000000000000041021524103652300137700ustar00rootroot00000000000000[project] name = "s2geometry" description = "Computational geometry and spatial indexing on the sphere" readme = "README.md" authors = [ { name = "Dan Larkin-York", email = "dan@arangodb.com" }, { name = "Eric Veach", email = "ericv@google.com" }, { name = "Jesse Rosenstock", email = "jmr@google.com" }, { name = "Julien Basch", email = "julienbasch@google.com" }, { name = "Mike Playle", email = "mike@mythik.co.uk" }, { name = "Phil Elson", email = "pelson.pub@gmail.com" }, { name = "Robert Coup", email = "robert.coup@koordinates.com" }, { name = "Tiago Brito", email = "tiago.brito@90poe.io" }, { name = "Zachary Burnett", email = "zachary.r.burnett@gmail.com" }, ] requires-python = ">=3.10" classifiers = [ "Programming Language :: Python :: 3", "Operating System :: POSIX", ] dynamic = [ "version", ] license = "Apache-2.0" license-files = ["LICENSE", "NOTICE", "AUTHORS"] [project.urls] Source = "https://github.com/google/s2geometry" [dependency-groups] test = [ "pytest", ] [build-system] requires = [ "cmake_build_extension", "setuptools", "setuptools_scm[toml]", "swig", ] build-backend = "setuptools.build_meta" [tool.setuptools] zip-safe = false include-package-data = false [tool.setuptools.packages.find] where = [ "src", ] namespaces = false [tool.setuptools.package-dir] "" = "src" [tool.setuptools_scm] # The same as the default. See #450. # https://setuptools-scm.readthedocs.io/en/latest/config/#setuptools_scm._config.DEFAULT_TAG_REGEX tag_regex = "^(?:[\\w-]+-)?(?P[vV]?\\d+(?:\\.\\d+){0,2}[^\\+]*)(?:\\+.*)?$" [tool.cibuildwheel] # we only need to build with CPython 3.10 (because of the limited API / stable ABI) build = "cp310-*" test-groups = ["test"] test-requires = ["abi3audit"] test-command = "pytest {project}/src/python/s2geometry_test.py && abi3audit --strict --report {project}/dist/*.whl" [tool.cibuildwheel.macos] # delocate is not needed because BUILD_SHARED_LIBS is OFF in setup.py, # so all dependencies are statically linked into the extension module. repair-wheel-command = "" setup.py000066400000000000000000000025301524103652300125710ustar00rootroot00000000000000from pathlib import Path import sys import cmake_build_extension import setuptools setuptools.setup( ext_modules=[ cmake_build_extension.CMakeExtension( # This could be anything you like, it is used to create build folders name="SwigBindings", # Name of the resulting package name (import s2geometry) install_prefix="s2geometry", # Selects the folder where the main CMakeLists.txt is stored # (it could be a subfolder) source_dir=str(Path(__file__).parent.absolute()), cmake_configure_options=[ # This option points CMake to the right Python interpreter, and helps # the logic of FindPython3.cmake to find the active version f"-DPython3_ROOT_DIR={Path(sys.prefix)}", "-DCALL_FROM_SETUP_PY:BOOL=ON", "-DBUILD_SHARED_LIBS:BOOL=OFF", "-DCMAKE_POSITION_INDEPENDENT_CODE=ON", "-DWITH_PYTHON=ON", "-DBUILD_TESTS=OFF", "-DFETCH_ABSEIL=ON", "-DWITH_PYTHON_LIMITED_API=ON", ], ), ], options={"bdist_wheel": {"py_limited_api": "cp310"}}, cmdclass=dict( # Enable the CMakeExtension entries defined above build_ext=cmake_build_extension.BuildExtension, ), ) src/000077500000000000000000000000001524103652300116465ustar00rootroot00000000000000src/.bazelrc000066400000000000000000000004311524103652300132670ustar00rootroot00000000000000# Enable Bzlmod for every Bazel command common --enable_bzlmod common --cxxopt=-std=c++20 common --announce_rc # Faster tests than fastbuild (-O0). build:dev --copt=-O1 # CI-specific flags common:ci --color=yes build:ci --show_progress_rate_limit=10 test:ci --test_output=errors src/BUILD.bazel000066400000000000000000001127731524103652300135370ustar00rootroot00000000000000load("@bazel_skylib//rules:common_settings.bzl", "bool_flag") load("@rules_cc//cc:defs.bzl", "cc_binary", "cc_library", "cc_test") package(default_visibility = ["//visibility:public"]) bool_flag( name = "use_openssl", build_setting_default = False, ) config_setting( name = "use_openssl_setting", flag_values = {":use_openssl": "True"}, ) cc_library( name = "s2", srcs = [ ":s2/encoded_s2cell_id_vector.cc", ":s2/encoded_s2point_vector.cc", ":s2/encoded_s2shape_index.cc", ":s2/encoded_string_vector.cc", ":s2/id_set_lexicon.cc", ":s2/internal/s2incident_edge_tracker.cc", ":s2/internal/s2index_cell_data.cc", ":s2/mutable_s2shape_index.cc", ":s2/r2rect.cc", ":s2/s1angle.cc", ":s2/s1chord_angle.cc", ":s2/s1interval.cc", ":s2/s2boolean_operation.cc", ":s2/s2buffer_operation.cc", ":s2/s2builder.cc", ":s2/s2builder_graph.cc", ":s2/s2builderutil_closed_set_normalizer.cc", ":s2/s2builderutil_find_polygon_degeneracies.cc", ":s2/s2builderutil_get_snapped_winding_delta.cc", ":s2/s2builderutil_lax_polygon_layer.cc", ":s2/s2builderutil_lax_polyline_layer.cc", ":s2/s2builderutil_s2point_vector_layer.cc", ":s2/s2builderutil_s2polygon_layer.cc", ":s2/s2builderutil_s2polyline_layer.cc", ":s2/s2builderutil_s2polyline_vector_layer.cc", ":s2/s2builderutil_snap_functions.cc", ":s2/s2cap.cc", ":s2/s2cell.cc", ":s2/s2cell_id.cc", ":s2/s2cell_index.cc", ":s2/s2cell_union.cc", ":s2/s2centroids.cc", ":s2/s2closest_cell_query.cc", ":s2/s2closest_edge_query.cc", ":s2/s2closest_point_query.cc", ":s2/s2contains_vertex_query.cc", ":s2/s2convex_hull_query.cc", ":s2/s2coords.cc", ":s2/s2crossing_edge_query.cc", ":s2/s2debug.cc", ":s2/s2earth.cc", ":s2/s2edge_clipping.cc", ":s2/s2edge_crosser.cc", ":s2/s2edge_crossings.cc", ":s2/s2edge_distances.cc", ":s2/s2edge_tessellator.cc", ":s2/s2error.cc", ":s2/s2fractal.cc", ":s2/s2furthest_edge_query.cc", ":s2/s2hausdorff_distance_query.cc", ":s2/s2latlng.cc", ":s2/s2latlng_rect.cc", ":s2/s2latlng_rect_bounder.cc", ":s2/s2lax_loop_shape.cc", ":s2/s2lax_polygon_shape.cc", ":s2/s2lax_polyline_shape.cc", ":s2/s2loop.cc", ":s2/s2loop_measures.cc", ":s2/s2max_distance_targets.cc", ":s2/s2measures.cc", ":s2/s2memory_tracker.cc", ":s2/s2metrics.cc", ":s2/s2min_distance_targets.cc", ":s2/s2padded_cell.cc", ":s2/s2point_compression.cc", ":s2/s2point_region.cc", ":s2/s2pointutil.cc", ":s2/s2polygon.cc", ":s2/s2polyline.cc", ":s2/s2polyline_alignment.cc", ":s2/s2polyline_measures.cc", ":s2/s2polyline_simplifier.cc", ":s2/s2predicates.cc", ":s2/s2projections.cc", ":s2/s2r2rect.cc", ":s2/s2region_coverer.cc", ":s2/s2region_intersection.cc", ":s2/s2region_term_indexer.cc", ":s2/s2region_union.cc", ":s2/s2shape_index.cc", ":s2/s2shape_index_buffered_region.cc", ":s2/s2shape_index_measures.cc", ":s2/s2shape_measures.cc", ":s2/s2shape_nesting_query.cc", ":s2/s2shapeutil_build_polygon_boundaries.cc", ":s2/s2shapeutil_coding.cc", ":s2/s2shapeutil_contains_brute_force.cc", ":s2/s2shapeutil_conversion.cc", ":s2/s2shapeutil_edge_iterator.cc", ":s2/s2shapeutil_edge_wrap.cc", ":s2/s2shapeutil_get_reference_point.cc", ":s2/s2shapeutil_visit_crossing_edge_pairs.cc", ":s2/s2text_format.cc", ":s2/s2wedge_relations.cc", ":s2/s2winding_operation.cc", ], hdrs = [ ":s2/_fp_contract_off.h", ":s2/encoded_s2cell_id_vector.h", ":s2/encoded_s2point_vector.h", ":s2/encoded_s2shape_index.h", ":s2/encoded_string_vector.h", ":s2/encoded_uint_vector.h", ":s2/id_set_lexicon.h", ":s2/internal/s2disjoint_set.h", ":s2/internal/s2incident_edge_tracker.h", ":s2/internal/s2index_cell_data.h", ":s2/internal/s2meta.h", ":s2/mutable_s2shape_index.h", ":s2/r1interval.h", ":s2/r2.h", ":s2/r2rect.h", ":s2/s1angle.h", ":s2/s1chord_angle.h", ":s2/s1interval.h", ":s2/s2boolean_operation.h", ":s2/s2buffer_operation.h", ":s2/s2builder.h", ":s2/s2builder_graph.h", ":s2/s2builder_layer.h", ":s2/s2builderutil_closed_set_normalizer.h", ":s2/s2builderutil_find_polygon_degeneracies.h", ":s2/s2builderutil_get_snapped_winding_delta.h", ":s2/s2builderutil_graph_shape.h", ":s2/s2builderutil_lax_polygon_layer.h", ":s2/s2builderutil_lax_polyline_layer.h", ":s2/s2builderutil_s2point_vector_layer.h", ":s2/s2builderutil_s2polygon_layer.h", ":s2/s2builderutil_s2polyline_layer.h", ":s2/s2builderutil_s2polyline_vector_layer.h", ":s2/s2builderutil_snap_functions.h", ":s2/s2builderutil_testing.h", ":s2/s2cap.h", ":s2/s2cell.h", ":s2/s2cell_id.h", ":s2/s2cell_index.h", ":s2/s2cell_iterator.h", ":s2/s2cell_iterator_join.h", ":s2/s2cell_range_iterator.h", ":s2/s2cell_union.h", ":s2/s2centroids.h", ":s2/s2closest_cell_query.h", ":s2/s2closest_cell_query_base.h", ":s2/s2closest_edge_query.h", ":s2/s2closest_edge_query_base.h", ":s2/s2closest_point_query.h", ":s2/s2closest_point_query_base.h", ":s2/s2coder.h", ":s2/s2contains_point_query.h", ":s2/s2contains_vertex_query.h", ":s2/s2convex_hull_query.h", ":s2/s2coords.h", ":s2/s2coords_internal.h", ":s2/s2crossing_edge_query.h", ":s2/s2debug.h", ":s2/s2distance_target.h", ":s2/s2earth.h", ":s2/s2edge_clipping.h", ":s2/s2edge_crosser.h", ":s2/s2edge_crossings.h", ":s2/s2edge_crossings_internal.h", ":s2/s2edge_distances.h", ":s2/s2edge_tessellator.h", ":s2/s2edge_vector_shape.h", ":s2/s2error.h", ":s2/s2fractal.h", ":s2/s2furthest_edge_query.h", ":s2/s2hausdorff_distance_query.h", ":s2/s2latlng.h", ":s2/s2latlng_rect.h", ":s2/s2latlng_rect_bounder.h", ":s2/s2lax_loop_shape.h", ":s2/s2lax_polygon_shape.h", ":s2/s2lax_polyline_shape.h", ":s2/s2loop.h", ":s2/s2loop_measures.h", ":s2/s2max_distance_targets.h", ":s2/s2measures.h", ":s2/s2memory_tracker.h", ":s2/s2metrics.h", ":s2/s2min_distance_targets.h", ":s2/s2padded_cell.h", ":s2/s2point.h", ":s2/s2point_array.h", ":s2/s2point_compression.h", ":s2/s2point_index.h", ":s2/s2point_region.h", ":s2/s2point_span.h", ":s2/s2point_vector_shape.h", ":s2/s2pointutil.h", ":s2/s2polygon.h", ":s2/s2polyline.h", ":s2/s2polyline_alignment.h", ":s2/s2polyline_alignment_internal.h", ":s2/s2polyline_measures.h", ":s2/s2polyline_simplifier.h", ":s2/s2predicates.h", ":s2/s2predicates_internal.h", ":s2/s2projections.h", ":s2/s2r2rect.h", ":s2/s2region.h", ":s2/s2region_coverer.h", ":s2/s2region_intersection.h", ":s2/s2region_term_indexer.h", ":s2/s2region_union.h", ":s2/s2shape.h", ":s2/s2shape_index.h", ":s2/s2shape_index_buffered_region.h", ":s2/s2shape_index_measures.h", ":s2/s2shape_index_region.h", ":s2/s2shape_measures.h", ":s2/s2shape_nesting_query.h", ":s2/s2shapeutil_build_polygon_boundaries.h", ":s2/s2shapeutil_coding.h", ":s2/s2shapeutil_contains_brute_force.h", ":s2/s2shapeutil_conversion.h", ":s2/s2shapeutil_count_edges.h", ":s2/s2shapeutil_edge_iterator.h", ":s2/s2shapeutil_edge_wrap.h", ":s2/s2shapeutil_get_reference_point.h", ":s2/s2shapeutil_shape_edge.h", ":s2/s2shapeutil_shape_edge_id.h", ":s2/s2shapeutil_testing.h", ":s2/s2shapeutil_visit_crossing_edge_pairs.h", ":s2/s2text_format.h", ":s2/s2validation_query.h", ":s2/s2wedge_relations.h", ":s2/s2winding_operation.h", ":s2/s2wrapped_shape.h", ":s2/sequence_lexicon.h", ":s2/thread_testing.h", ":s2/value_lexicon.h", ], deps = [ "//s2/base:casts", "//s2/base:log_severity", "//s2/base:spinlock", "//s2/testing:gtest_prod", "//s2/util/bitmap", "//s2/util/bits", "//s2/util/coding", "//s2/util/endian", "//s2/util/gtl:compact_array", "//s2/util/gtl:container_logging", "//s2/util/gtl:dense_hash_set", "//s2/util/gtl:requires", "//s2/util/gtl:unaligned", "//s2/util/gtl:value_or_die", "//s2/util/hash:mix", "//s2/util/math:mathutil", "//s2/util/math:matrix3x3", "//s2/util/math:vector", "//s2/util/math/exactfloat", "//s2/util/random", "//s2/util/task:status_macros", "//s2/util/units", "@abseil-cpp//absl/base", "@abseil-cpp//absl/container:btree", "@abseil-cpp//absl/container:flat_hash_set", "@abseil-cpp//absl/flags:flag", "@abseil-cpp//absl/log:absl_log", "@abseil-cpp//absl/log:check", "@abseil-cpp//absl/random:bit_gen_ref", "@abseil-cpp//absl/status", "@abseil-cpp//absl/status:statusor", ], ) cc_binary( name = "s2shared", srcs = [ ":s2/encoded_s2cell_id_vector.cc", ":s2/encoded_s2point_vector.cc", ":s2/encoded_s2shape_index.cc", ":s2/encoded_string_vector.cc", ":s2/id_set_lexicon.cc", ":s2/mutable_s2shape_index.cc", ":s2/r2rect.cc", ":s2/s1angle.cc", ":s2/s1chord_angle.cc", ":s2/s1interval.cc", ":s2/s2boolean_operation.cc", ":s2/s2buffer_operation.cc", ":s2/s2builder.cc", ":s2/s2builder_graph.cc", ":s2/s2builderutil_closed_set_normalizer.cc", ":s2/s2builderutil_find_polygon_degeneracies.cc", ":s2/s2builderutil_get_snapped_winding_delta.cc", ":s2/s2builderutil_lax_polygon_layer.cc", ":s2/s2builderutil_lax_polyline_layer.cc", ":s2/s2builderutil_s2point_vector_layer.cc", ":s2/s2builderutil_s2polygon_layer.cc", ":s2/s2builderutil_s2polyline_layer.cc", ":s2/s2builderutil_s2polyline_vector_layer.cc", ":s2/s2builderutil_snap_functions.cc", ":s2/s2cap.cc", ":s2/s2cell.cc", ":s2/s2cell_id.cc", ":s2/s2cell_index.cc", ":s2/s2cell_union.cc", ":s2/s2centroids.cc", ":s2/s2closest_cell_query.cc", ":s2/s2closest_edge_query.cc", ":s2/s2closest_point_query.cc", ":s2/s2contains_vertex_query.cc", ":s2/s2convex_hull_query.cc", ":s2/s2coords.cc", ":s2/s2crossing_edge_query.cc", ":s2/s2debug.cc", ":s2/s2earth.cc", ":s2/s2edge_clipping.cc", ":s2/s2edge_crosser.cc", ":s2/s2edge_crossings.cc", ":s2/s2edge_distances.cc", ":s2/s2edge_tessellator.cc", ":s2/s2error.cc", ":s2/s2fractal.cc", ":s2/s2furthest_edge_query.cc", ":s2/s2hausdorff_distance_query.cc", ":s2/s2latlng.cc", ":s2/s2latlng_rect.cc", ":s2/s2latlng_rect_bounder.cc", ":s2/s2lax_loop_shape.cc", ":s2/s2lax_polygon_shape.cc", ":s2/s2lax_polyline_shape.cc", ":s2/s2loop.cc", ":s2/s2loop_measures.cc", ":s2/s2max_distance_targets.cc", ":s2/s2measures.cc", ":s2/s2memory_tracker.cc", ":s2/s2metrics.cc", ":s2/s2min_distance_targets.cc", ":s2/s2padded_cell.cc", ":s2/s2point_compression.cc", ":s2/s2point_region.cc", ":s2/s2pointutil.cc", ":s2/s2polygon.cc", ":s2/s2polyline.cc", ":s2/s2polyline_alignment.cc", ":s2/s2polyline_measures.cc", ":s2/s2polyline_simplifier.cc", ":s2/s2predicates.cc", ":s2/s2projections.cc", ":s2/s2r2rect.cc", ":s2/s2region_coverer.cc", ":s2/s2region_intersection.cc", ":s2/s2region_term_indexer.cc", ":s2/s2region_union.cc", ":s2/s2shape_index.cc", ":s2/s2shape_index_buffered_region.cc", ":s2/s2shape_index_measures.cc", ":s2/s2shape_measures.cc", ":s2/s2shape_nesting_query.cc", ":s2/s2shapeutil_build_polygon_boundaries.cc", ":s2/s2shapeutil_coding.cc", ":s2/s2shapeutil_contains_brute_force.cc", ":s2/s2shapeutil_conversion.cc", ":s2/s2shapeutil_edge_iterator.cc", ":s2/s2shapeutil_get_reference_point.cc", ":s2/s2shapeutil_visit_crossing_edge_pairs.cc", ":s2/s2text_format.cc", ":s2/s2wedge_relations.cc", ":s2/s2winding_operation.cc", ], linkshared = True, deps = [ ":s2", ], ) cc_library( name = "s2_testing_headers", testonly = True, srcs = [ ":s2/gmock_matchers.cc", ":s2/s2builderutil_testing.cc", ":s2/s2random.cc", ":s2/s2shapeutil_testing.cc", ":s2/s2testing.cc", ":s2/thread_testing.cc", ], hdrs = [ ":s2/gmock_matchers.h", ":s2/s2builderutil_testing.h", ":s2/s2cell_iterator_testing.h", ":s2/s2closest_edge_query_testing.h", ":s2/s2coder_testing.h", ":s2/s2random.h", ":s2/s2shapeutil_testing.h", ":s2/s2testing.h", ":s2/thread_testing.h", ], includes = ["src"], deps = [ ":s2", "//s2/base:timer", "@abseil-cpp//absl/base", "@abseil-cpp//absl/flags:flag", "@abseil-cpp//absl/hash:hash_testing", "@abseil-cpp//absl/log:absl_log", "@abseil-cpp//absl/log:check", "@abseil-cpp//absl/log:log_streamer", "@abseil-cpp//absl/status", "@abseil-cpp//absl/status:statusor", "@abseil-cpp//absl/strings:cord", "@googletest//:gtest", ], ) cc_test( name = "s2disjoint_set_test", srcs = [":s2/internal/s2disjoint_set_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2fractal_test", srcs = [":s2/s2fractal_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "encoded_s2cell_id_vector_test", srcs = [":s2/encoded_s2cell_id_vector_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "encoded_s2point_vector_test", srcs = [":s2/encoded_s2point_vector_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "encoded_s2shape_index_test", srcs = [":s2/encoded_s2shape_index_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "encoded_string_vector_test", srcs = [":s2/encoded_string_vector_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "encoded_uint_vector_test", srcs = [":s2/encoded_uint_vector_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "id_set_lexicon_test", srcs = [":s2/id_set_lexicon_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "mutable_s2shape_index_test", srcs = [":s2/mutable_s2shape_index_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "r1interval_test", srcs = [":s2/r1interval_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "r2rect_test", srcs = [":s2/r2rect_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s1angle_test", srcs = [":s2/s1angle_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s1chord_angle_test", srcs = [":s2/s1chord_angle_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s1interval_test", srcs = [":s2/s1interval_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2boolean_operation_test", srcs = [":s2/s2boolean_operation_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2buffer_operation_test", srcs = [":s2/s2buffer_operation_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builder_graph_test", srcs = [":s2/s2builder_graph_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builder_test", srcs = [":s2/s2builder_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_closed_set_normalizer_test", srcs = [":s2/s2builderutil_closed_set_normalizer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_find_polygon_degeneracies_test", srcs = [":s2/s2builderutil_find_polygon_degeneracies_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_get_snapped_winding_delta_test", srcs = [":s2/s2builderutil_get_snapped_winding_delta_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_lax_polygon_layer_test", srcs = [":s2/s2builderutil_lax_polygon_layer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_lax_polyline_layer_test", srcs = [":s2/s2builderutil_lax_polyline_layer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_s2point_vector_layer_test", srcs = [":s2/s2builderutil_s2point_vector_layer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_s2polygon_layer_test", srcs = [":s2/s2builderutil_s2polygon_layer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_s2polyline_layer_test", srcs = [":s2/s2builderutil_s2polyline_layer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_s2polyline_vector_layer_test", srcs = [":s2/s2builderutil_s2polyline_vector_layer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_snap_functions_test", srcs = [":s2/s2builderutil_snap_functions_test.cc"], # https://github.com/google/s2geometry/issues/596 flaky = True, shard_count = 3, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2builderutil_testing_test", srcs = [":s2/s2builderutil_testing_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cap_test", srcs = [":s2/s2cap_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_test", srcs = [":s2/s2cell_test.cc"], # https://github.com/google/s2geometry/issues/505 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_id_test", srcs = [":s2/s2cell_id_test.cc"], # https://github.com/google/s2geometry/issues/516 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_index_test", srcs = [":s2/s2cell_index_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_iterator_join_test", srcs = [":s2/s2cell_iterator_join_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_iterator_testing_test", srcs = [":s2/s2cell_iterator_testing_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_range_iterator_test", srcs = [":s2/s2cell_range_iterator_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2cell_union_test", srcs = [":s2/s2cell_union_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2centroids_test", srcs = [":s2/s2centroids_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2closest_cell_query_base_test", srcs = [":s2/s2closest_cell_query_base_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2closest_cell_query_test", srcs = [":s2/s2closest_cell_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2closest_edge_query_base_test", srcs = [":s2/s2closest_edge_query_base_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2closest_edge_query_test", srcs = [":s2/s2closest_edge_query_test.cc"], # https://github.com/google/s2geometry/issues/552 # https://github.com/google/s2geometry/issues/582 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2closest_point_query_base_test", srcs = [":s2/s2closest_point_query_base_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2closest_point_query_test", srcs = [":s2/s2closest_point_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2contains_point_query_test", srcs = [":s2/s2contains_point_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2contains_vertex_query_test", srcs = [":s2/s2contains_vertex_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2convex_hull_query_test", srcs = [":s2/s2convex_hull_query_test.cc"], # https://github.com/google/s2geometry/issues/515 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2coords_test", srcs = [":s2/s2coords_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2crossing_edge_query_test", srcs = [":s2/s2crossing_edge_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2earth_test", srcs = [":s2/s2earth_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2edge_clipping_test", srcs = [":s2/s2edge_clipping_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2edge_crosser_test", srcs = [":s2/s2edge_crosser_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2edge_crossings_test", srcs = [":s2/s2edge_crossings_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2edge_distances_test", srcs = [":s2/s2edge_distances_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2edge_tessellator_test", srcs = [":s2/s2edge_tessellator_test.cc"], shard_count = 2, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2edge_vector_shape_test", srcs = [":s2/s2edge_vector_shape_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2error_test", srcs = [":s2/s2error_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2furthest_edge_query_test", srcs = [":s2/s2furthest_edge_query_test.cc"], # https://github.com/google/s2geometry/issues/592 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2hausdorff_distance_query_test", srcs = [":s2/s2hausdorff_distance_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2index_cell_data_test", srcs = [":s2/internal/s2index_cell_data_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2latlng_test", srcs = [":s2/s2latlng_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2latlng_rect_bounder_test", srcs = [":s2/s2latlng_rect_bounder_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2latlng_rect_test", srcs = [":s2/s2latlng_rect_test.cc"], # https://github.com/google/s2geometry/issues/523 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2lax_loop_shape_test", srcs = [":s2/s2lax_loop_shape_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2lax_polygon_shape_test", srcs = [":s2/s2lax_polygon_shape_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2lax_polyline_shape_test", srcs = [":s2/s2lax_polyline_shape_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2loop_measures_test", srcs = [":s2/s2loop_measures_test.cc"], # https://github.com/google/s2geometry/issues/395 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2loop_test", srcs = [":s2/s2loop_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", "@abseil-cpp//absl/status:status_matchers", ], ) cc_test( name = "s2measures_test", srcs = [":s2/s2measures_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2memory_tracker_test", srcs = [":s2/s2memory_tracker_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2metrics_test", srcs = [":s2/s2metrics_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2max_distance_targets_test", srcs = [":s2/s2max_distance_targets_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2min_distance_targets_test", srcs = [":s2/s2min_distance_targets_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2padded_cell_test", srcs = [":s2/s2padded_cell_test.cc"], # https://github.com/google/s2geometry/issues/598 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2point_test", srcs = [":s2/s2point_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2point_vector_shape_test", srcs = [":s2/s2point_vector_shape_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2point_compression_test", srcs = [":s2/s2point_compression_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2point_index_test", srcs = [":s2/s2point_index_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2point_region_test", srcs = [":s2/s2point_region_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2pointutil_test", srcs = [":s2/s2pointutil_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2polygon_test", srcs = [":s2/s2polygon_test.cc"], flaky = True, shard_count = 5, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2polyline_alignment_test", srcs = [":s2/s2polyline_alignment_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2polyline_simplifier_test", srcs = [":s2/s2polyline_simplifier_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2polyline_measures_test", srcs = [":s2/s2polyline_measures_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2polyline_test", srcs = [":s2/s2polyline_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2predicates_test", srcs = [":s2/s2predicates_test.cc"], # https://github.com/google/s2geometry/issues/511 # https://github.com/google/s2geometry/issues/612 flaky = True, deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2projections_test", srcs = [":s2/s2projections_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2r2rect_test", srcs = [":s2/s2r2rect_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2region_test", srcs = [":s2/s2region_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2region_term_indexer_test", srcs = [":s2/s2region_term_indexer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2region_coverer_test", srcs = [":s2/s2region_coverer_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2region_union_test", srcs = [":s2/s2region_union_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shape_index_buffered_region_test", srcs = [":s2/s2shape_index_buffered_region_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shape_index_measures_test", srcs = [":s2/s2shape_index_measures_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shape_index_region_test", srcs = [":s2/s2shape_index_region_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shape_index_test", srcs = [":s2/s2shape_index_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shape_measures_test", srcs = [":s2/s2shape_measures_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shape_nesting_query_test", srcs = [":s2/s2shape_nesting_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_build_polygon_boundaries_test", srcs = [":s2/s2shapeutil_build_polygon_boundaries_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_coding_test", srcs = [":s2/s2shapeutil_coding_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_contains_brute_force_test", srcs = [":s2/s2shapeutil_contains_brute_force_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_conversion_test", srcs = [":s2/s2shapeutil_conversion_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_count_edges_test", srcs = [":s2/s2shapeutil_count_edges_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_edge_iterator_test", srcs = [":s2/s2shapeutil_edge_iterator_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_edge_wrap_test", srcs = [":s2/s2shapeutil_edge_wrap_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_get_reference_point_test", srcs = [":s2/s2shapeutil_get_reference_point_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2shapeutil_visit_crossing_edge_pairs_test", srcs = [":s2/s2shapeutil_visit_crossing_edge_pairs_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) #cc_test( # name = "s2testing_test", # srcs = [":s2/s2testing_test.cc"], # deps = [ # ":s2", # ":s2_testing_headers", # "//s2/testing:test_main", # ], #) cc_test( name = "s2text_format_test", srcs = [":s2/s2text_format_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2validation_query_test", srcs = [":s2/s2validation_query_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2wedge_relations_test", srcs = [":s2/s2wedge_relations_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2winding_operation_test", srcs = [":s2/s2winding_operation_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "s2wrapped_shape_test", srcs = [":s2/s2wrapped_shape_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "sequence_lexicon_test", srcs = [":s2/sequence_lexicon_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) cc_test( name = "value_lexicon_test", srcs = [":s2/value_lexicon_test.cc"], deps = [ ":s2", ":s2_testing_headers", "//s2/testing:test_main", ], ) src/MODULE.bazel000066400000000000000000000022241524103652300136520ustar00rootroot00000000000000module( name = "s2geometry", version = "head", bazel_compatibility = [ ">=8.0.0", ], compatibility_level = 1, ) # Production dependencies bazel_dep(name = "abseil-cpp", version = "20260526.0") bazel_dep(name = "bazel_skylib", version = "1.9.0") bazel_dep(name = "rules_cc", version = "0.2.22") # Development dependencies (only needed for tests) bazel_dep(name = "boringssl", version = "0.20260616.0", dev_dependency = True) bazel_dep(name = "openssl", version = "3.5.5.bcr.3", dev_dependency = True) bazel_dep(name = "google_benchmark", version = "1.9.5", dev_dependency = True) bazel_dep(name = "googletest", version = "1.17.0.bcr.2", dev_dependency = True) # Python configuration # The platforms dependency is needed for pybind_extension rules. See: # https://github.com/pybind/pybind11_bazel/blob/master/MODULE.bazel bazel_dep(name = "platforms", version = "1.1.0") bazel_dep(name = "pybind11_bazel", version = "3.0.1") bazel_dep(name = "rules_python", version = "2.3.1") # Extensions cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension", dev_dependency = True) use_repo(cc_configure, "local_config_cc") src/python/000077500000000000000000000000001524103652300131675ustar00rootroot00000000000000src/python/BUILD.bazel000066400000000000000000000112001524103652300150370ustar00rootroot00000000000000load("@pybind11_bazel//:build_defs.bzl", "pybind_extension", "pybind_library") load("@rules_cc//cc:defs.bzl", "cc_library", "cc_test") load("@rules_python//python:defs.bzl", "py_library", "py_test") package(default_visibility = ["//visibility:private"]) # ======================================== # Python Package # ======================================== py_library( name = "s2geometry_pybind", srcs = ["s2geometry_pybind/__init__.py"], data = [ ":s2geometry_bindings", ], imports = ["."], visibility = ["//visibility:public"], ) # ======================================== # C++ Bindings # ======================================== pybind_extension( name = "s2geometry_bindings", srcs = ["module.cc"], deps = [ ":r1interval_bindings", ":r2point_bindings", ":r2rect_bindings", ":s1angle_bindings", ":s1chord_angle_bindings", ":s1interval_bindings", ":s2cap_bindings", ":s2cell_bindings", ":s2cell_id_bindings", ":s2latlng_bindings", ":s2point_bindings", ], ) pybind_library( name = "r1interval_bindings", srcs = ["r1interval_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", ], ) pybind_library( name = "r2point_bindings", srcs = ["r2point_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", ], ) pybind_library( name = "r2rect_bindings", srcs = ["r2rect_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", ], ) pybind_library( name = "s1angle_bindings", srcs = ["s1angle_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", "@abseil-cpp//absl/strings", ], ) pybind_library( name = "s1chord_angle_bindings", srcs = ["s1chord_angle_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", "@abseil-cpp//absl/strings", ], ) pybind_library( name = "s1interval_bindings", srcs = ["s1interval_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", "@abseil-cpp//absl/strings", ], ) pybind_library( name = "s2point_bindings", srcs = ["s2point_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", ], ) pybind_library( name = "s2latlng_bindings", srcs = ["s2latlng_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", "@abseil-cpp//absl/strings", ], ) cc_library( name = "s2cell_id_range", srcs = ["s2cell_id_range.cc"], hdrs = ["s2cell_id_range.h"], deps = [ "//:s2", "@abseil-cpp//absl/log:absl_check", ], ) pybind_library( name = "s2cell_id_bindings", srcs = ["s2cell_id_bindings.cc"], deps = [ ":s2cell_id_range", "//:s2", "@abseil-cpp//absl/strings", ], ) cc_test( name = "s2cell_id_range_test", srcs = ["s2cell_id_range_test.cc"], deps = [ ":s2cell_id_range", "//:s2", "//s2/testing:test_main", ], ) pybind_library( name = "s2cap_bindings", srcs = ["s2cap_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", ], ) pybind_library( name = "s2cell_bindings", srcs = ["s2cell_bindings.cc"], deps = [ "//:s2", "@abseil-cpp//absl/hash", "@abseil-cpp//absl/strings", ], ) # ======================================== # Python Tests # ======================================== py_test( name = "r1interval_test", srcs = ["r1interval_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s1angle_test", srcs = ["s1angle_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s1chord_angle_test", srcs = ["s1chord_angle_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "r2point_test", srcs = ["r2point_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "r2rect_test", srcs = ["r2rect_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s1interval_test", srcs = ["s1interval_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s2point_test", srcs = ["s2point_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s2latlng_test", srcs = ["s2latlng_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s2cap_test", srcs = ["s2cap_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s2cell_id_test", srcs = ["s2cell_id_test.py"], deps = [":s2geometry_pybind"], ) py_test( name = "s2cell_test", srcs = ["s2cell_test.py"], deps = [":s2geometry_pybind"], ) src/python/CMakeLists.txt000066400000000000000000000047171524103652300157400ustar00rootroot00000000000000# Generate standard target names. cmake_policy(SET CMP0078 NEW) # Honor SWIG_MODULE_NAME via -module flag. cmake_policy(SET CMP0086 NEW) # Handle where to install the resulting Python package if (CALL_FROM_SETUP_PY) # The CMakeExtension will set CMAKE_INSTALL_PREFIX to the root # of the resulting wheel archive set(S2GEOMETRY_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}) else() # The Python package is installed directly in the folder of the # detected interpreter (system, user, or virtualenv) set(S2GEOMETRY_INSTALL_PREFIX ${Python3_SITELIB}) endif() include(${SWIG_USE_FILE}) include_directories(${Python3_INCLUDE_DIRS}) # SWIG does not understand `uint64_t`. `SWIGWORDSIZE64` controls whether # it maps `uint64_t` to `unsigned long` or `unsigned long long`. # (See `stdint.i`.) `SWIGWORDSIZE64` should really be called # `INT64_IS_LONG_INT`. Unices other that macOS use `long`. Windows uses # `long long`. If you get error involving `vector` # and `vector` while compiling `s2PYTHON_wrap.cxx`, then # this is probably defined incorrectly. # https://github.com/swig/swig/issues/2923 if (CMAKE_SIZEOF_VOID_P EQUAL 8 AND UNIX AND NOT APPLE) set(CMAKE_SWIG_FLAGS "-DSWIGWORDSIZE64") else() set(CMAKE_SWIG_FLAGS "") endif() set_property(SOURCE s2.i PROPERTY SWIG_FLAGS "-module" "s2geometry") set_property(SOURCE s2.i PROPERTY CPLUSPLUS ON) swig_add_library(s2geometry LANGUAGE python SOURCES s2.i) if (WITH_PYTHON_LIMITED_API) target_link_libraries(s2geometry Python3::SABIModule s2) # https://www.swig.org/Doc4.2/Python.html#Python_stable_abi target_compile_definitions(s2geometry PRIVATE Py_LIMITED_API=0x030a0000) else() target_link_libraries(s2geometry Python3::Module s2) endif() enable_testing() add_test(NAME s2geometry_test COMMAND ${Python3_EXECUTABLE} "${PROJECT_SOURCE_DIR}/src/python/s2geometry_test.py") set_property(TEST s2geometry_test PROPERTY ENVIRONMENT "PYTHONPATH=$ENV{PYTHONPATH}:${PROJECT_BINARY_DIR}/python") # Install the wrapper. install(TARGETS s2geometry DESTINATION ${S2GEOMETRY_INSTALL_PREFIX}) # Install swig-generated Python file (we rename it to __init__.py as it will # ultimately end up in a directory called s2geometry in site-packages, which will # serve as the module directory. install(FILES "${CMAKE_CURRENT_BINARY_DIR}/s2geometry.py" DESTINATION ${S2GEOMETRY_INSTALL_PREFIX} RENAME __init__.py COMPONENT s2geometry) src/python/README.md000066400000000000000000000214361524103652300144540ustar00rootroot00000000000000# S2 Geometry Pybind11 Bindings *UNDER DEVELOPMENT* This directory contains SWIG and pybind11-based Python SDK for S2 Geometry. ## Migration Strategy The S2 Geometry library is transitioning from SWIG-based bindings to pybind11-based bindings. During this migration: - **SWIG bindings** (`s2geometry`): The current production bindings, built with CMake. Use `import s2geometry` to access these. - **pybind11 bindings** (`s2geometry_pybind`): The new bindings under development, built with Bazel. Use `import s2geometry_pybind` to access these. Once the pybind11 bindings are feature-complete and stable, the SWIG bindings will be deprecated and the pybind11 package will be renamed to `s2geometry` to become the primary Python API. ## User Guide ### Usage Example ```python import s2geometry_pybind as s2 p1 = s2.S2Point(1.0, 0.0, 0.0) p2 = s2.S2Point(0.0, 1.0, 0.0) sum_point = p1 + p2 print(sum_point) ``` ### Interface Notes The Python bindings follow the C++ API closely but with Pythonic conventions: **Naming Conventions:** - Core classes exist within the top-level module; we may define submodules for utility classes. - Class names remain unchanged (e.g., `S2Point`, `S1Angle`, `R1Interval`) - Method names are converted to snake_case (converted from UpperCamelCase C++ function names) - The `Get` prefix is dropped: C++ `GetDistance` becomes Python `distance`, `GetBoundUV` becomes `bound_uv`, etc. **Properties vs. Methods:** - Simple accessors that return internal state (including trivial unit conversions) are properties: `point.x`, `point.y`, `interval.lo`, `interval.hi`, `angle.radians`, `angle.degrees` - Properties are always read-only. To create a modified object, use a constructor or factory method. - Other functions are methods: `interval.length()`, `angle.normalized()`, `angle.sin()` **Invalid Values:** - Invalid inputs to constructions or functions raises `ValueError`. - Example: `S1Interval(0.0, 4.0)` raises `ValueError` because `4.0 > π`. - Some classes change the behavior of operations to guarantee validity. - Example: `S2LatLng` arithmetic operators automatically clamp the result to a valid range whereas in C++ these operators can produce invalid states. - Note: In C++, these conditions trigger `ABSL_DCHECK` assertions. The bindings prevent these assertions from firing by pre-validating inputs. - Note: Python bindings check for invalid inputs and throw C++ exceptions which are caught by pybind and converted to Python exceptions. Exceptions are normally prohibited by the C++ style guide, but this is the preferred approach for pybind. **Documentation:** - Python docstrings provide essential information about parameters, return values, and key behaviors - For comprehensive documentation including edge cases and algorithmic details, refer to the C++ header files - The C++ documentation is the authoritative source of truth **Operators:** - Standard Python operators work as expected: `+`, `-`, `*`, `==`, `!=`, `<`, `>` (for C++ classes that implement those operators) - Types that define `__eq__` also define `__hash__`, so they can be used as dictionary keys and in sets. - Binding types are intentionally immutable. In-place mutation operators are not supported. Augmented assignment (`+=`, `-=`, `*=`, `/=`) still works: Python falls back to the binary operator and rebinds the variable (e.g. `a += b` is equivalent to `a = a + b`). **Method Overloads:** - Instead of Python overloads, C++ overloaded methods are exposed under distinct names. For different argument types, the short name is used for the same-type argument and a longer name for other types (e.g., `R2Rect.contains(other: R2Rect)` and `R2Rect.contains_point(p: R2Point)`). For overloads with significantly different behavior, descriptive names are chosen (e.g., `R2Rect.vertex(k)` for CCW vertex index and `R2Rect.vertex_ij(i, j)` for axis-direction vertex access). **Default Values:** - Some methods have default parameter values (e.g., `approx_equals(other, max_error=1e-15)`). These defaults are re-defined in the Python bindings and are expected to match the C++ defaults. **String Representations:** - `repr()` prefixes the class name and delegates to C++ `operator<<` for the value - `str()` delegates to C++ `operator<<` for a cleaner output - Example: `repr(S1Interval(0.0, 2.0))` returns `'S1Interval([0, 2])'` while `str()` returns `'[0, 2]'` **Vector Inheritance:** - In C++, various geometry classes inherit from or expose vector types (e.g., `S2Point` inherits from `Vector3_d`, `R2Point` is a type alias for `Vector2_d`, `R1Interval` returns bounds as `Vector2_d`) - The Python bindings do **not** expose this inheritance hierarchy; it is treated as an implementation detail - Instead, classes that inherit from a vector expose key functions from the `BasicVector` interface (e.g., `norm()`, `dot_prod()`, `cross_prod()`) - C++ functions that accept or return a vector object use a Python tuple (of length matching the vector dimension) - Array indexing operators (e.g., `point[0]`) are not currently supported **Iterators:** - Some classes expose methods that return iterables (e.g., `S2CellId.children()`, `S2CellId.cells(level)`). - Iterables support forward iteration, `len()`, indexing, slicing, `in`, and `reversed()` unless otherwise noted. **Serialization:** - The C++ Encoder/Decoder serialization functions are not currently supported ## Development ### Directory Structure ``` python/ ├── module.cc # Binding module entry point ├── s2point_bindings.cc # Bindings for S2Point (add more *_bindings.cc as needed) ├── s2geometry_pybind/ # Dir for Python package │ └── __init__.py # Package initialization ├── s2point_test.py # Tests for S2Point (add more *_test.py as needed) └── BUILD.bazel # Build rules for bindings, library, and tests ``` ### Building with Bazel (pybind11 bindings) Bazel can be used for development and testing of the new pybind11-based bindings. To run all tests: ```bash cd src bazel test //python/... ``` ### Building with CMake (SWIG bindings) CMake currently builds **only the SWIG-based bindings** (the legacy `s2geometry` package). The pybind11 bindings are not yet integrated into the CMake build system. For detailed CMake build instructions, dependency installation, and Python wheel creation, see the [parent directory README](../README.md#build-and-install). Key points: - Install dependencies: `sudo apt-get install cmake libssl-dev swig python3-dev` - Enable Python bindings with `-DWITH_PYTHON=ON` when running cmake - This will build the SWIG-based `s2geometry` package only Example: ```bash mkdir build && cd build cmake -DBUILD_TESTS=yes -DWITH_PYTHON=ON -DCMAKE_PREFIX_PATH=/path/to/absl/install -DCMAKE_CXX_STANDARD=17 .. make -j $(nproc) make test ARGS="-j$(nproc)" sudo make install ``` To run the SWIG tests directly without cmake: ```bash cd build/python PYTHONPATH=. python3 ../../src/python/s2geometry_test.py ``` **Note:** Once the pybind11 bindings are complete, they will be integrated into the CMake build system as a replacement for the SWIG bindings. ## Extending the Bindings To add bindings for a new class: 1. Create `_bindings.cc` with pybind11 bindings 2. Update `BUILD.bazel` to add a new `pybind_library` target 3. Update `module.cc` to call your binding function 4. Create tests in `_test.py` ### Binding File Organization Use the following sections to organize functions within the bindings files and tests. Secondarily, follow the order in which functions are declared in the C++ headers. 1. **Constructors** - Default constructors and constructors with parameters 1. **Constants** - Class-level constants in upper snake case (e.g., `S2CellId.MAX_LEVEL`, `S2CellId.NUM_FACES`). Accessible as class attributes. 1. **Factory methods** - Static factory methods (e.g., `from_degrees`, `from_radians`, `zero`, `invalid`) 1. **Properties** - Mutable and read-only properties (e.g., coordinate accessors like `x`, `y`, `lo`, `hi`) 1. **Predicates** - Simple boolean state checks (e.g., `is_empty`, `is_valid`, `is_full`) 1. **Geometric operations** - All other methods including conversions, computations, containment checks, set operations, normalization, and distance calculations 1. **Traversal** - Methods for navigating a cell hierarchy (e.g., `parent`, `child`, neighbor methods) 1. **Vector operations** - Methods from the Vector base class (e.g., `norm`, `norm2`, `normalize`, `dot_prod`, `cross_prod`, `angle`). Only applicable to classes that inherit from `util/math/vector.h` 1. **Operators** - Operator overloads (e.g., `==`, `+`, `*`, comparison operators) 1. **String representation** - `__repr__` (which also provides `__str__`), and string conversion methods like `to_string_in_degrees` 1. **Module-level functions** - Standalone functions (e.g., trigonometric functions for S1Angle) src/python/coder.i000066400000000000000000000076101524103652300144410ustar00rootroot00000000000000// // Exposes Encoder and Decoder a subset of functionality plus the // ability to set and get internal buffer. This allows passing them // into other SWIG'd methods, such as those in the S2 SWIG library. // For example: // // class S2Polygon { // ... // void Encode(Encoder* const encoder) const override; // // bool Decode(Decoder* const decoder) override; // }; // // Usage: // # data is a bytes object. // dec = pywrapcoder.Decoder(data) // polygon = s2.S2Polygon() // polygon.Decode(dec) // // enc = pywrapcoder.Encoder() // polygon.Encode(enc) // data = enc.buffer() // %{ #include "s2/util/coding/coder.h" %} // For Decoder::reset to accept a bytes or bytearray object. %typemap(in) (const void* buf, size_t maxn) { if (PyBytes_Check($input)) { $1 = (void *) PyBytes_AsString($input); $2 = PyBytes_Size($input); } else if (PyByteArray_Check($input)) { $1 = (void *) PyByteArray_AsString($input); $2 = PyByteArray_Size($input); } else { // TODO: When Py_LIMITED_API is raised to 3.13+ (2028), replace // %S/(PyObject*)Py_TYPE() with %T in PyErr_Format calls for bare type // names (e.g. "int" vs ""). PyErr_Format(PyExc_TypeError, "bytes or bytearray needed, %S found", (PyObject*)Py_TYPE($input)); return nullptr; } }; // For Encoder::reset to accept a bytearray object. %typemap(in) (void* buf, size_t maxn) { if (PyByteArray_Check($input)) { $1 = (void *) PyByteArray_AsString($input); $2 = PyByteArray_Size($input); } else { PyErr_Format(PyExc_TypeError, "bytearray needed, %S found", (PyObject*)Py_TYPE($input)); return nullptr; } }; // Keep a reference to the object so that outside users don't // have to keep one, or else it could be released. // The auto-generated code passes *args to each of the methods, but the use // cases we support is only when a single arg is passed in. %pythonprepend Decoder::Decoder %{ if len(args) == 1: self._data_keepalive = args[0] %} %pythonprepend Decoder::reset %{ self._data_keepalive = args[0] %} %extend Decoder { // Allows direct construction with a bytes or bytearray objects. Decoder(PyObject *obj) { if (PyBytes_Check(obj)) { return new Decoder(PyBytes_AsString(obj), PyBytes_Size(obj)); } if (PyByteArray_Check(obj)) { return new Decoder(PyByteArray_AsString(obj), PyByteArray_Size(obj)); } PyErr_Format(PyExc_TypeError, "bytes or bytearray needed, %S found", (PyObject*)Py_TYPE(obj)); return nullptr; } } %extend Encoder { // Returns internal buffer as a bytearray. PyObject* buffer() { return PyByteArray_FromStringAndSize($self->base(), $self->length()); } } %ignoreall %unignore Decoder; %unignore Decoder::Decoder(); %unignore Decoder::Decoder(const void*, size_t); %unignore Decoder::~Decoder; %unignore Decoder::avail() const; %unignore Decoder::get8(); %unignore Decoder::get16(); %unignore Decoder::get32(); %unignore Decoder::get64(); %unignore Decoder::getfloat(); %unignore Decoder::getdouble(); %unignore Decoder::pos() const; %unignore Decoder::reset(const void*, size_t); %unignore Encoder; %unignore Encoder::Encoder(); %unignore Encoder::Encoder(void*, size_t); %unignore Encoder::~Encoder; %unignore Encoder::Ensure(size_t); %unignore Encoder::avail() const; %unignore Encoder::buffer(); %unignore Encoder::clear(); %unignore Encoder::length() const; %unignore Encoder::put8(unsigned char); %unignore Encoder::put16(uint16_t); %unignore Encoder::put32(uint32_t); %unignore Encoder::put64(uint64_t); %unignore Encoder::putdouble(double); %unignore Encoder::putfloat(float); %unignore Encoder::reset(void *, size_t); // Silence SWIG Warning 362: operator= can't be wrapped in Python. // %ignoreall is active but the warning fires at parse time regardless. %ignore Encoder::operator=; %include "s2/util/coding/coder.h" %unignoreall src/python/module.cc000066400000000000000000000024331524103652300147650ustar00rootroot00000000000000#include namespace py = pybind11; // Forward declarations for binding functions // keep-sorted start void bind_r1interval(py::module& m); void bind_r2point(py::module& m); void bind_r2rect(py::module& m); void bind_s1angle(py::module& m); void bind_s1chord_angle(py::module& m); void bind_s1interval(py::module& m); void bind_s2cap(py::module& m); void bind_s2cell(py::module& m); void bind_s2cell_id(py::module& m); void bind_s2latlng(py::module& m); void bind_s2point(py::module& m); // keep-sorted end PYBIND11_MODULE(s2geometry_bindings, m) { m.doc() = "S2 Geometry Python bindings using pybind11"; // Bind core geometry classes in dependency order. // Each class must be registered before classes that use it as a // parameter or return type. // No dependencies bind_r1interval(m); bind_r2point(m); bind_s1interval(m); bind_s2point(m); // Deps: r1interval, r2point bind_r2rect(m); // Deps: s2point bind_s1angle(m); // Deps: s1angle, s2point bind_s1chord_angle(m); // Deps: s1angle, s1chord_angle, s2point bind_s2cap(m); // Deps: s1angle, s2point bind_s2latlng(m); // Deps: s1angle, s2point, s2latlng, r2point, r2rect bind_s2cell_id(m); // Deps: r2rect, s1chord_angle, s2cap, s2cell_id, s2latlng, s2point bind_s2cell(m); } src/python/r1interval_bindings.cc000066400000000000000000000126271524103652300174520ustar00rootroot00000000000000#include #include #include #include "absl/hash/hash.h" #include "s2/r1interval.h" namespace py = pybind11; void bind_r1interval(py::module& m) { py::class_(m, "R1Interval") // Constructors .def(py::init<>(), "Default constructor creates an empty interval") .def(py::init(), py::arg("lo"), py::arg("hi"), "Constructor that accepts the endpoints of the interval.\n\n" "If lo > hi, the interval is empty.") // Static factory methods .def_static("empty", &R1Interval::Empty, "Returns the empty interval") .def_static("from_point", &R1Interval::FromPoint, py::arg("p"), "Constructs an interval containing a single point") .def_static("from_point_pair", &R1Interval::FromPointPair, py::arg("p1"), py::arg("p2"), "Constructs the minimal interval containing two points") // Properties .def_property_readonly("lo", &R1Interval::lo, "Lower bound") .def_property_readonly("hi", &R1Interval::hi, "Upper bound") .def("bounds", [](const R1Interval& self) { return py::make_tuple(self.lo(), self.hi()); }, "Return bounds as a tuple (lo, hi)") // Predicates .def("is_empty", &R1Interval::is_empty, "Return true if the interval is empty, i.e. it contains no points") // Geometric operations .def("center", &R1Interval::GetCenter, "Return the center of the interval.\n\n" "For empty intervals, the result is arbitrary.") .def("length", &R1Interval::GetLength, "Return the length of the interval.\n\n" "The length of an empty interval is negative.") .def("contains_point", py::overload_cast( &R1Interval::Contains, py::const_), py::arg("p"), "Return true if the interval contains the point 'p'") .def("interior_contains_point", py::overload_cast( &R1Interval::InteriorContains, py::const_), py::arg("p"), "Return true if the interior of the interval contains the point 'p'") .def("contains", py::overload_cast( &R1Interval::Contains, py::const_), py::arg("other"), "Return true if the interval contains the given interval") .def("interior_contains", py::overload_cast( &R1Interval::InteriorContains, py::const_), py::arg("other"), "Return true if the interior of this interval contains the entire " "interval 'other'") .def("intersects", &R1Interval::Intersects, py::arg("other"), "Return true if the two intervals contain any points in common") .def("interior_intersects", &R1Interval::InteriorIntersects, py::arg("other"), "Return true if the interior of this interval intersects any point " "of the given interval") .def("add_point", &R1Interval::AddPoint, py::arg("p"), "Expand the interval to include the given point 'p'") .def("add_interval", &R1Interval::AddInterval, py::arg("other"), "Expand the interval to include the given interval") .def("project", [](const R1Interval& self, double p) { if (self.is_empty()) { throw py::value_error("Cannot project onto an empty interval"); } return self.Project(p); }, py::arg("p"), "Return the closest point in the interval to 'p'.\n\n" "The interval must be non-empty.") .def("expanded", &R1Interval::Expanded, py::arg("margin"), "Return interval expanded on each side by 'margin'.\n\n" "If 'margin' is negative, shrink the interval instead. The " "resulting interval may be empty. Any expansion of an empty " "interval remains empty.") .def("union", &R1Interval::Union, py::arg("other"), "Return the smallest interval containing this interval and 'other'") .def("intersection", &R1Interval::Intersection, py::arg("other"), "Return the intersection of this interval with 'other'") .def("directed_hausdorff_distance", &R1Interval::GetDirectedHausdorffDistance, py::arg("other"), "Return the directed Hausdorff distance to 'other'") // Note: default value must match C++ signature in r1interval.h .def("approx_equals", &R1Interval::ApproxEquals, py::arg("other"), py::arg("max_error") = 1e-15, "Return true if approximately equal to 'other'.\n\n" "The empty interval is considered to be positioned arbitrarily, " "thus any interval with length <= 2*max_error matches the empty " "interval.") // Operators .def(py::self == py::self, "Return true if two intervals contain the same set of points") .def(py::self != py::self, "Return true if two intervals do not contain the same set of points") .def("__hash__", [](const R1Interval& self) { return absl::HashOf(self); }) // String representation .def("__repr__", [](const R1Interval& i) { std::ostringstream oss; oss << "R1Interval(" << i << ")"; return oss.str(); }) .def("__str__", [](const R1Interval& i) { std::ostringstream oss; oss << i; return oss.str(); }); } src/python/r1interval_test.py000066400000000000000000000223451524103652300166750ustar00rootroot00000000000000"""Tests for R1Interval pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestR1Interval(unittest.TestCase): """Test cases for R1Interval bindings.""" # Constructors def test_default_constructor(self): interval = s2.R1Interval() self.assertTrue(interval.is_empty()) def test_constructor_with_bounds(self): interval = s2.R1Interval(1.0, 3.0) self.assertEqual(interval.lo, 1.0) self.assertEqual(interval.hi, 3.0) self.assertFalse(interval.is_empty()) def test_constructor_lo_greater_than_hi_is_empty(self): interval = s2.R1Interval(3.0, 1.0) self.assertTrue(interval.is_empty()) def test_constructor_negative_values(self): interval = s2.R1Interval(-5.0, -2.0) self.assertEqual(interval.lo, -5.0) self.assertEqual(interval.hi, -2.0) self.assertFalse(interval.is_empty()) def test_constructor_large_values(self): interval = s2.R1Interval(-1e10, 1e10) self.assertEqual(interval.lo, -1e10) self.assertEqual(interval.hi, 1e10) # Static factory methods def test_empty(self): empty = s2.R1Interval.empty() self.assertTrue(empty.is_empty()) def test_from_point(self): interval = s2.R1Interval.from_point(5.0) self.assertEqual(interval.lo, 5.0) self.assertEqual(interval.hi, 5.0) self.assertFalse(interval.is_empty()) def test_from_point_pair(self): interval = s2.R1Interval.from_point_pair(5.0, 2.0) self.assertEqual(interval.lo, 2.0) self.assertEqual(interval.hi, 5.0) self.assertTrue(interval.contains_point(3.0)) def test_from_point_pair_ordered(self): interval = s2.R1Interval.from_point_pair(2.0, 5.0) self.assertEqual(interval.lo, 2.0) self.assertEqual(interval.hi, 5.0) # Properties def test_properties_lo_hi(self): interval = s2.R1Interval(1.0, 3.0) self.assertEqual(interval.lo, 1.0) self.assertEqual(interval.hi, 3.0) def test_lo_hi_are_readonly(self): interval = s2.R1Interval(1.0, 3.0) with self.assertRaises(AttributeError): interval.lo = 0.5 with self.assertRaises(AttributeError): interval.hi = 0.5 def test_bounds(self): interval = s2.R1Interval(1.0, 3.0) bounds = interval.bounds() self.assertEqual(bounds, (1.0, 3.0)) # Predicates def test_is_empty(self): self.assertTrue(s2.R1Interval().is_empty()) self.assertTrue(s2.R1Interval.empty().is_empty()) self.assertFalse(s2.R1Interval(1.0, 3.0).is_empty()) self.assertFalse(s2.R1Interval(1.0, 1.0).is_empty()) # single point # Geometric operations def test_center(self): interval = s2.R1Interval(1.0, 3.0) self.assertAlmostEqual(interval.center(), 2.0) def test_length(self): interval = s2.R1Interval(1.0, 3.0) self.assertAlmostEqual(interval.length(), 2.0) def test_length_empty_is_negative(self): empty = s2.R1Interval.empty() self.assertLess(empty.length(), 0) def test_contains_point(self): interval = s2.R1Interval(1.0, 3.0) self.assertTrue(interval.contains_point(1.0)) # lo boundary self.assertTrue(interval.contains_point(2.0)) # interior self.assertTrue(interval.contains_point(3.0)) # hi boundary self.assertFalse(interval.contains_point(0.5)) # below self.assertFalse(interval.contains_point(3.5)) # above def test_interior_contains_point(self): interval = s2.R1Interval(1.0, 3.0) self.assertFalse(interval.interior_contains_point(1.0)) # lo boundary self.assertTrue(interval.interior_contains_point(2.0)) # interior self.assertFalse(interval.interior_contains_point(3.0)) # hi boundary def test_contains_interval(self): outer = s2.R1Interval(1.0, 5.0) inner = s2.R1Interval(2.0, 4.0) disjoint = s2.R1Interval(6.0, 8.0) self.assertTrue(outer.contains(inner)) self.assertFalse(inner.contains(outer)) self.assertFalse(outer.contains(disjoint)) def test_contains_empty_interval(self): interval = s2.R1Interval(1.0, 3.0) empty = s2.R1Interval.empty() self.assertTrue(interval.contains(empty)) def test_interior_contains_interval(self): outer = s2.R1Interval(1.0, 5.0) inner = s2.R1Interval(2.0, 4.0) boundary = s2.R1Interval(1.0, 5.0) self.assertTrue(outer.interior_contains(inner)) self.assertFalse(outer.interior_contains(boundary)) def test_intersects(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(2.0, 4.0) i3 = s2.R1Interval(4.0, 6.0) self.assertTrue(i1.intersects(i2)) self.assertFalse(i1.intersects(i3)) def test_interior_intersects(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(2.0, 4.0) touching = s2.R1Interval(3.0, 5.0) self.assertTrue(i1.interior_intersects(i2)) self.assertFalse(i1.interior_intersects(touching)) def test_add_point(self): interval = s2.R1Interval(1.0, 3.0) interval.add_point(5.0) self.assertEqual(interval.hi, 5.0) interval.add_point(-1.0) self.assertEqual(interval.lo, -1.0) def test_add_point_to_empty(self): interval = s2.R1Interval() interval.add_point(2.0) self.assertEqual(interval.lo, 2.0) self.assertEqual(interval.hi, 2.0) def test_add_interval(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(2.0, 5.0) i1.add_interval(i2) self.assertEqual(i1.lo, 1.0) self.assertEqual(i1.hi, 5.0) def test_project(self): interval = s2.R1Interval(1.0, 3.0) self.assertAlmostEqual(interval.project(2.0), 2.0) # inside self.assertAlmostEqual(interval.project(0.0), 1.0) # below self.assertAlmostEqual(interval.project(5.0), 3.0) # above def test_project_on_empty_raises(self): with self.assertRaises(ValueError): s2.R1Interval.empty().project(1.0) def test_expanded(self): interval = s2.R1Interval(1.0, 3.0) expanded = interval.expanded(0.5) self.assertAlmostEqual(expanded.lo, 0.5) self.assertAlmostEqual(expanded.hi, 3.5) def test_expanded_shrink(self): interval = s2.R1Interval(1.0, 3.0) shrunk = interval.expanded(-0.5) self.assertAlmostEqual(shrunk.lo, 1.5) self.assertAlmostEqual(shrunk.hi, 2.5) def test_expanded_empty_stays_empty(self): empty = s2.R1Interval.empty() expanded = empty.expanded(1.0) self.assertTrue(expanded.is_empty()) def test_union(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(5.0, 7.0) union = i1.union(i2) self.assertEqual(union.lo, 1.0) self.assertEqual(union.hi, 7.0) def test_intersection(self): i1 = s2.R1Interval(1.0, 5.0) i2 = s2.R1Interval(3.0, 7.0) intersection = i1.intersection(i2) self.assertEqual(intersection.lo, 3.0) self.assertEqual(intersection.hi, 5.0) def test_intersection_disjoint(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(5.0, 7.0) intersection = i1.intersection(i2) self.assertTrue(intersection.is_empty()) def test_directed_hausdorff_distance(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(2.0, 5.0) dist = i1.directed_hausdorff_distance(i2) # max of (1-2, 3-5) clamped to 0 = max(0, 0) = 0 # Actually: max(0, max(hi-y.hi, y.lo-lo)) = max(0, max(3-5, 2-1)) = max(0, 1) = 1 self.assertAlmostEqual(dist, 1.0) def test_directed_hausdorff_distance_empty(self): empty = s2.R1Interval.empty() i = s2.R1Interval(1.0, 3.0) self.assertAlmostEqual(empty.directed_hausdorff_distance(i), 0.0) def test_approx_equals(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(1.0, 3.0) i3 = s2.R1Interval(1.0, 3.0 + 1e-16) i4 = s2.R1Interval(1.0, 3.1) self.assertTrue(i1.approx_equals(i2)) self.assertTrue(i1.approx_equals(i3)) self.assertFalse(i1.approx_equals(i4)) self.assertTrue(i1.approx_equals(i4, 0.2)) # Operators def test_equality(self): i1 = s2.R1Interval(1.0, 3.0) i2 = s2.R1Interval(1.0, 3.0) i3 = s2.R1Interval(1.0, 4.0) self.assertTrue(i1 == i2) self.assertTrue(i1 != i3) def test_empty_intervals_are_equal(self): e1 = s2.R1Interval.empty() e2 = s2.R1Interval() self.assertTrue(e1 == e2) def test_hash(self): a = s2.R1Interval(0.0, 1.0) b = s2.R1Interval(0.0, 1.0) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_string_representation(self): interval = s2.R1Interval(1.0, 3.0) self.assertEqual(repr(interval), "R1Interval([1, 3])") self.assertEqual(str(interval), "[1, 3]") def test_string_representation_empty(self): empty = s2.R1Interval.empty() self.assertEqual(repr(empty), "R1Interval([1, 0])") self.assertEqual(str(empty), "[1, 0]") if __name__ == "__main__": unittest.main() src/python/r2point_bindings.cc000066400000000000000000000065001524103652300167510ustar00rootroot00000000000000#include #include #include #include "absl/hash/hash.h" #include "s2/r2.h" namespace py = pybind11; void bind_r2point(py::module& m) { py::class_(m, "R2Point") // Constructors .def(py::init<>(), "Default constructor creates a zero vector") .def(py::init(), py::arg("x"), py::arg("y"), "Constructor that accepts x, y coordinates") .def(py::init([](py::tuple t) { if (t.size() != 2) { throw py::value_error("Tuple must have exactly 2 elements"); } return R2Point(t[0].cast(), t[1].cast()); }), py::arg("coords"), "Constructor that accepts a tuple of (x, y) coordinates") // Properties .def_property_readonly("x", py::overload_cast<>(&R2Point::x, py::const_), "The x coordinate") .def_property_readonly("y", py::overload_cast<>(&R2Point::y, py::const_), "The y coordinate") .def("data", [](const R2Point& self) { return py::make_tuple(self.x(), self.y()); }, "Return coordinates as a tuple (x, y)") // Vector operations .def("norm", &R2Point::Norm, "Return the Euclidean norm (length)") .def("norm2", &R2Point::Norm2, "Return the squared Euclidean norm") .def("normalize", &R2Point::Normalize, "Return a normalized copy of the vector.\n\n" "Returns a unit vector if the norm is nonzero.") .def("dot_prod", [](const R2Point& self, const R2Point& other) { return self.DotProd(other); }, py::arg("other"), "Return the dot product with another point") .def("cross_prod", [](const R2Point& self, const R2Point& other) { return self.CrossProd(other); }, py::arg("other"), "Return the cross product with another point (scalar for 2D)") .def("angle", [](const R2Point& self, const R2Point& other) { return self.Angle(other); }, py::arg("other"), "Return the angle between this and another point (radians).\n\n" "The result is in the range [-pi, pi].") .def("ortho", &R2Point::Ortho, "Return a perpendicular vector (rotated 90 degrees CCW)") .def("fabs", &R2Point::Fabs, "Return a vector with component-wise absolute values") // Operators .def(py::self + py::self, "Add two points (vector addition)") .def(py::self - py::self, "Subtract two points (vector subtraction)") .def(py::self * double(), "Multiply by scalar") .def("__rmul__", [](const R2Point& self, double v) -> R2Point { return self * v; }, "Multiply by scalar (reversed operands)") .def(py::self / double(), "Divide by scalar") .def(-py::self, "Negate point") .def(py::self == py::self, "Return true if points are exactly equal") .def(py::self != py::self, "Return true if points are not exactly equal") .def("__hash__", [](const R2Point& self) { return absl::HashOf(self); }) // String representation .def("__repr__", [](const R2Point& p) { std::ostringstream oss; oss << "R2Point(" << p << ")"; return oss.str(); }) .def("__str__", [](const R2Point& p) { std::ostringstream oss; oss << p; return oss.str(); }); } src/python/r2point_test.py000066400000000000000000000125261524103652300162030ustar00rootroot00000000000000"""Tests for R2Point pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestR2Point(unittest.TestCase): """Test cases for R2Point bindings.""" # Constructors def test_default_constructor(self): p = s2.R2Point() self.assertEqual(p.x, 0.0) self.assertEqual(p.y, 0.0) def test_constructor_with_coordinates(self): p = s2.R2Point(1.0, 2.0) self.assertEqual(p.x, 1.0) self.assertEqual(p.y, 2.0) def test_constructor_from_tuple(self): p = s2.R2Point((3.0, 4.0)) self.assertEqual(p.x, 3.0) self.assertEqual(p.y, 4.0) def test_constructor_from_tuple_wrong_length(self): with self.assertRaises(ValueError): s2.R2Point((1.0,)) with self.assertRaises(ValueError): s2.R2Point((1.0, 2.0, 3.0)) # Properties def test_properties_are_readonly(self): p = s2.R2Point(1.0, 2.0) with self.assertRaises(AttributeError): p.x = 5.0 with self.assertRaises(AttributeError): p.y = 5.0 def test_data(self): p = s2.R2Point(1.0, 2.0) coords = p.data() self.assertEqual(coords, (1.0, 2.0)) # Vector operations def test_norm(self): p = s2.R2Point(3.0, 4.0) self.assertAlmostEqual(p.norm(), 5.0) self.assertAlmostEqual(p.norm2(), 25.0) def test_normalize(self): p = s2.R2Point(3.0, 4.0) normalized = p.normalize() self.assertAlmostEqual(normalized.norm(), 1.0) self.assertAlmostEqual(normalized.x, 0.6) self.assertAlmostEqual(normalized.y, 0.8) def test_dot_product(self): p1 = s2.R2Point(1.0, 0.0) p2 = s2.R2Point(0.0, 1.0) p3 = s2.R2Point(2.0, 3.0) self.assertAlmostEqual(p1.dot_prod(p2), 0.0) self.assertAlmostEqual(p1.dot_prod(p3), 2.0) def test_cross_product(self): p1 = s2.R2Point(1.0, 0.0) p2 = s2.R2Point(0.0, 1.0) # 2D cross product returns scalar: x1*y2 - y1*x2 self.assertAlmostEqual(p1.cross_prod(p2), 1.0) def test_angle(self): p1 = s2.R2Point(1.0, 0.0) p2 = s2.R2Point(0.0, 1.0) self.assertAlmostEqual(p1.angle(p2), math.pi / 2) def test_ortho(self): p = s2.R2Point(1.0, 0.0) o = p.ortho() # Rotated 90 degrees CCW: (1, 0) -> (0, 1) self.assertAlmostEqual(o.x, 0.0) self.assertAlmostEqual(o.y, 1.0) def test_ortho_general(self): p = s2.R2Point(3.0, 4.0) o = p.ortho() # Should be perpendicular self.assertAlmostEqual(p.dot_prod(o), 0.0) # Same norm self.assertAlmostEqual(o.norm(), p.norm()) def test_fabs(self): p = s2.R2Point(-3.0, -4.0) a = p.fabs() self.assertAlmostEqual(a.x, 3.0) self.assertAlmostEqual(a.y, 4.0) def test_fabs_mixed(self): p = s2.R2Point(-1.0, 2.0) a = p.fabs() self.assertAlmostEqual(a.x, 1.0) self.assertAlmostEqual(a.y, 2.0) # Operators def test_addition(self): p1 = s2.R2Point(1.0, 2.0) p2 = s2.R2Point(3.0, 4.0) result = p1 + p2 self.assertAlmostEqual(result.x, 4.0) self.assertAlmostEqual(result.y, 6.0) def test_subtraction(self): p1 = s2.R2Point(3.0, 4.0) p2 = s2.R2Point(1.0, 2.0) result = p1 - p2 self.assertAlmostEqual(result.x, 2.0) self.assertAlmostEqual(result.y, 2.0) def test_scalar_multiplication(self): p = s2.R2Point(1.0, 2.0) result1 = p * 3.0 result2 = 3.0 * p for result in [result1, result2]: self.assertAlmostEqual(result.x, 3.0) self.assertAlmostEqual(result.y, 6.0) def test_scalar_division(self): p = s2.R2Point(4.0, 6.0) result = p / 2.0 self.assertAlmostEqual(result.x, 2.0) self.assertAlmostEqual(result.y, 3.0) def test_negation(self): p = s2.R2Point(1.0, -2.0) result = -p self.assertAlmostEqual(result.x, -1.0) self.assertAlmostEqual(result.y, 2.0) def test_equality(self): p1 = s2.R2Point(1.0, 2.0) p2 = s2.R2Point(1.0, 2.0) p3 = s2.R2Point(1.0, 3.0) self.assertEqual(p1, p2) self.assertNotEqual(p1, p3) def test_add_assign(self): p = s2.R2Point(1.0, 2.0) p += s2.R2Point(3.0, 4.0) self.assertAlmostEqual(p.x, 4.0) self.assertAlmostEqual(p.y, 6.0) def test_sub_assign(self): p = s2.R2Point(3.0, 4.0) p -= s2.R2Point(1.0, 2.0) self.assertAlmostEqual(p.x, 2.0) self.assertAlmostEqual(p.y, 2.0) def test_mul_assign(self): p = s2.R2Point(1.0, 2.0) p *= 3.0 self.assertAlmostEqual(p.x, 3.0) self.assertAlmostEqual(p.y, 6.0) def test_div_assign(self): p = s2.R2Point(4.0, 6.0) p /= 2.0 self.assertAlmostEqual(p.x, 2.0) self.assertAlmostEqual(p.y, 3.0) def test_hash(self): a = s2.R2Point(1.0, 2.0) b = s2.R2Point(1.0, 2.0) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_string_representation(self): p = s2.R2Point(1.0, 2.0) self.assertEqual(repr(p), "R2Point([1, 2])") self.assertEqual(str(p), "[1, 2]") if __name__ == "__main__": unittest.main() src/python/r2rect_bindings.cc000066400000000000000000000172711524103652300165640ustar00rootroot00000000000000#include #include #include #include "absl/hash/hash.h" #include "s2/r2rect.h" namespace py = pybind11; namespace { void MaybeThrowInvalidRect(const R2Point& lo, const R2Point& hi) { // Both x and y intervals must be either both empty or both non-empty. bool x_empty = lo.x() > hi.x(); bool y_empty = lo.y() > hi.y(); if (x_empty != y_empty) { std::ostringstream oss; oss << "Invalid R2Rect: x and y intervals must be both empty or both " << "non-empty, got lo=" << lo << " hi=" << hi; throw py::value_error(oss.str()); } } } // namespace void bind_r2rect(py::module& m) { py::class_(m, "R2Rect") // Constructors .def(py::init<>(), "Default constructor creates an empty rectangle") .def(py::init([](const R2Point& lo, const R2Point& hi) { MaybeThrowInvalidRect(lo, hi); return R2Rect(lo, hi); }), py::arg("lo"), py::arg("hi"), "Constructor from lower-left and upper-right points.\n\n" "Raises ValueError if one axis interval is empty and the other " "is not.") .def(py::init([](const R1Interval& x, const R1Interval& y) { if (x.is_empty() != y.is_empty()) { throw py::value_error( "Invalid R2Rect: x and y intervals must be both empty or " "both non-empty"); } return R2Rect(x, y); }), py::arg("x"), py::arg("y"), "Constructor from x and y intervals.\n\n" "Both intervals must be either both empty or both non-empty.\n" "Raises ValueError if one is empty and the other is not.") // Static factory methods .def_static("empty", &R2Rect::Empty, "Returns the canonical empty rectangle") .def_static("from_center_size", [](const R2Point& center, const R2Point& size) { if (size.x() < 0 || size.y() < 0) { throw py::value_error( "Both components of size must be non-negative"); } return R2Rect::FromCenterSize(center, size); }, py::arg("center"), py::arg("size"), "Construct a rectangle from a center point and size.\n\n" "Both components of size must be non-negative.\n" "Raises ValueError if any size component is negative.") .def_static("from_point", &R2Rect::FromPoint, py::arg("p"), "Constructs a rectangle containing a single point") .def_static("from_point_pair", &R2Rect::FromPointPair, py::arg("p1"), py::arg("p2"), "Constructs the minimal bounding rectangle containing two " "points") // Properties .def_property_readonly("lo", &R2Rect::lo, "Lower-left corner of the rectangle") .def_property_readonly("hi", &R2Rect::hi, "Upper-right corner of the rectangle") .def_property_readonly("x", &R2Rect::x, "The x-interval") .def_property_readonly("y", &R2Rect::y, "The y-interval") // Predicates .def("is_valid", &R2Rect::is_valid, "Return true if the rectangle is valid") .def("is_empty", &R2Rect::is_empty, "Return true if the rectangle is empty") // Geometric operations .def("vertex", py::overload_cast(&R2Rect::GetVertex, py::const_), py::arg("k"), "Return the k-th vertex of the rectangle (k = 0,1,2,3) in CCW " "order.\n\n" "Vertex 0 is in the lower-left corner. The argument is reduced " "modulo 4.") .def("vertex_ij", [](const R2Rect& self, int i, int j) { return self.GetVertex(i, j); }, py::arg("i"), py::arg("j"), "Return the vertex in direction i along x-axis (0=left, 1=right) " "and direction j along y-axis (0=down, 1=up)") .def("center", &R2Rect::GetCenter, "Return the center of the rectangle") .def("size", &R2Rect::GetSize, "Return the width and height of the rectangle.\n\n" "Empty rectangles have a negative width and height.") .def("contains_point", py::overload_cast( &R2Rect::Contains, py::const_), py::arg("p"), "Return true if the rectangle contains the given point") .def("interior_contains_point", py::overload_cast( &R2Rect::InteriorContains, py::const_), py::arg("p"), "Return true if the interior of the rectangle contains the given " "point") .def("contains", py::overload_cast( &R2Rect::Contains, py::const_), py::arg("other"), "Return true if the rectangle contains the given other rectangle") .def("interior_contains", py::overload_cast( &R2Rect::InteriorContains, py::const_), py::arg("other"), "Return true if the interior of this rectangle contains all points " "of 'other'") .def("intersects", &R2Rect::Intersects, py::arg("other"), "Return true if this rectangle and 'other' have any points in " "common") .def("interior_intersects", &R2Rect::InteriorIntersects, py::arg("other"), "Return true if the interior of this rectangle intersects any " "point of 'other'") .def("add_point", &R2Rect::AddPoint, py::arg("p"), "Expand the rectangle to include the given point") .def("add_rect", &R2Rect::AddRect, py::arg("other"), "Expand the rectangle to include the given other rectangle") .def("project", [](const R2Rect& self, const R2Point& p) { if (self.is_empty()) { throw py::value_error( "Cannot project onto an empty rectangle"); } return self.Project(p); }, py::arg("p"), "Return the closest point in the rectangle to 'p'.\n\n" "The rectangle must be non-empty.") .def("expanded", py::overload_cast(&R2Rect::Expanded, py::const_), py::arg("margin"), "Return a rectangle expanded on each side by margin.\n\n" "margin.x() is applied on each side in the x-direction and " "margin.y() in the y-direction. If a margin component is negative, " "shrink the corresponding sides instead.") .def("union", &R2Rect::Union, py::arg("other"), "Return the smallest rectangle containing this rectangle and " "'other'") .def("intersection", &R2Rect::Intersection, py::arg("other"), "Return the smallest rectangle containing the intersection of " "this rectangle and 'other'") // Note: default value must match C++ signature in r2rect.h .def("approx_equals", &R2Rect::ApproxEquals, py::arg("other"), py::arg("max_error") = 1e-15, "Return true if approximately equal to 'other'") // Operators .def(py::self == py::self, "Return true if two rectangles are equal") .def(py::self != py::self, "Return true if two rectangles are not equal") .def("__hash__", [](const R2Rect& self) { return absl::HashOf(self); }) // String representation .def("__repr__", [](const R2Rect& r) { std::ostringstream oss; oss << "R2Rect(" << r << ")"; return oss.str(); }) .def("__str__", [](const R2Rect& r) { std::ostringstream oss; oss << r; return oss.str(); }); } src/python/r2rect_test.py000066400000000000000000000267501524103652300160130ustar00rootroot00000000000000"""Tests for R2Rect pybind11 bindings.""" import unittest import s2geometry_pybind as s2 class TestR2Rect(unittest.TestCase): """Test cases for R2Rect bindings.""" # Constructors def test_default_constructor(self): rect = s2.R2Rect() self.assertTrue(rect.is_empty()) def test_constructor_from_points(self): lo = s2.R2Point(1.0, 2.0) hi = s2.R2Point(3.0, 4.0) rect = s2.R2Rect(lo, hi) self.assertEqual(rect.lo, lo) self.assertEqual(rect.hi, hi) self.assertFalse(rect.is_empty()) def test_constructor_from_intervals(self): x = s2.R1Interval(1.0, 3.0) y = s2.R1Interval(2.0, 4.0) rect = s2.R2Rect(x, y) self.assertEqual(rect.x, x) self.assertEqual(rect.y, y) def test_constructor_from_intervals_both_empty(self): x = s2.R1Interval.empty() y = s2.R1Interval.empty() rect = s2.R2Rect(x, y) self.assertTrue(rect.is_empty()) def test_constructor_from_intervals_mixed_empty_raises(self): x = s2.R1Interval(1.0, 3.0) y = s2.R1Interval.empty() with self.assertRaises(ValueError): s2.R2Rect(x, y) def test_constructor_from_points_mixed_empty_raises(self): # lo.x > hi.x but lo.y < hi.y -> one axis empty, other not lo = s2.R2Point(3.0, 1.0) hi = s2.R2Point(1.0, 4.0) with self.assertRaises(ValueError): s2.R2Rect(lo, hi) # Static factory methods def test_empty(self): rect = s2.R2Rect.empty() self.assertTrue(rect.is_empty()) def test_from_point(self): p = s2.R2Point(1.0, 2.0) rect = s2.R2Rect.from_point(p) self.assertEqual(rect.lo, p) self.assertEqual(rect.hi, p) self.assertFalse(rect.is_empty()) def test_from_point_pair(self): p1 = s2.R2Point(3.0, 4.0) p2 = s2.R2Point(1.0, 2.0) rect = s2.R2Rect.from_point_pair(p1, p2) self.assertAlmostEqual(rect.lo.x, 1.0) self.assertAlmostEqual(rect.lo.y, 2.0) self.assertAlmostEqual(rect.hi.x, 3.0) self.assertAlmostEqual(rect.hi.y, 4.0) def test_from_center_size(self): center = s2.R2Point(2.0, 3.0) size = s2.R2Point(4.0, 6.0) rect = s2.R2Rect.from_center_size(center, size) self.assertAlmostEqual(rect.lo.x, 0.0) self.assertAlmostEqual(rect.lo.y, 0.0) self.assertAlmostEqual(rect.hi.x, 4.0) self.assertAlmostEqual(rect.hi.y, 6.0) def test_from_center_size_negative_raises(self): center = s2.R2Point(0.0, 0.0) with self.assertRaises(ValueError): s2.R2Rect.from_center_size(center, s2.R2Point(-1.0, 2.0)) with self.assertRaises(ValueError): s2.R2Rect.from_center_size(center, s2.R2Point(1.0, -2.0)) # Properties def test_lo_hi(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) self.assertAlmostEqual(rect.lo.x, 1.0) self.assertAlmostEqual(rect.lo.y, 2.0) self.assertAlmostEqual(rect.hi.x, 3.0) self.assertAlmostEqual(rect.hi.y, 4.0) def test_x_y(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) self.assertEqual(rect.x, s2.R1Interval(1.0, 3.0)) self.assertEqual(rect.y, s2.R1Interval(2.0, 4.0)) def test_properties_are_readonly(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) with self.assertRaises(AttributeError): rect.lo = s2.R2Point(0.0, 0.0) with self.assertRaises(AttributeError): rect.hi = s2.R2Point(0.0, 0.0) with self.assertRaises(AttributeError): rect.x = s2.R1Interval(0.0, 1.0) with self.assertRaises(AttributeError): rect.y = s2.R1Interval(0.0, 1.0) # Predicates def test_is_valid(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) self.assertTrue(rect.is_valid()) self.assertTrue(s2.R2Rect.empty().is_valid()) def test_is_empty(self): self.assertTrue(s2.R2Rect().is_empty()) self.assertTrue(s2.R2Rect.empty().is_empty()) rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) self.assertFalse(rect.is_empty()) # Geometric operations def test_vertex(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) # CCW: lower-left, lower-right, upper-right, upper-left v0 = rect.vertex(0) v1 = rect.vertex(1) v2 = rect.vertex(2) v3 = rect.vertex(3) self.assertEqual(v0, s2.R2Point(0.0, 0.0)) self.assertEqual(v1, s2.R2Point(1.0, 0.0)) self.assertEqual(v2, s2.R2Point(1.0, 1.0)) self.assertEqual(v3, s2.R2Point(0.0, 1.0)) def test_vertex_ij(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) self.assertEqual(rect.vertex_ij(0, 0), s2.R2Point(0.0, 0.0)) self.assertEqual(rect.vertex_ij(1, 0), s2.R2Point(1.0, 0.0)) self.assertEqual(rect.vertex_ij(0, 1), s2.R2Point(0.0, 1.0)) self.assertEqual(rect.vertex_ij(1, 1), s2.R2Point(1.0, 1.0)) def test_center(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 4.0)) center = rect.center() self.assertAlmostEqual(center.x, 1.0) self.assertAlmostEqual(center.y, 2.0) def test_size(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 6.0)) size = rect.size() self.assertAlmostEqual(size.x, 2.0) self.assertAlmostEqual(size.y, 4.0) def test_contains_point(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) self.assertTrue(rect.contains_point(s2.R2Point(1.0, 1.0))) # interior self.assertTrue(rect.contains_point(s2.R2Point(0.0, 0.0))) # corner self.assertTrue(rect.contains_point(s2.R2Point(2.0, 2.0))) # corner self.assertFalse(rect.contains_point(s2.R2Point(3.0, 1.0))) # outside def test_interior_contains_point(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) self.assertTrue(rect.interior_contains_point(s2.R2Point(1.0, 1.0))) self.assertFalse(rect.interior_contains_point(s2.R2Point(0.0, 0.0))) self.assertFalse(rect.interior_contains_point(s2.R2Point(2.0, 1.0))) def test_contains_rect(self): outer = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(4.0, 4.0)) inner = s2.R2Rect(s2.R2Point(1.0, 1.0), s2.R2Point(3.0, 3.0)) disjoint = s2.R2Rect(s2.R2Point(5.0, 5.0), s2.R2Point(6.0, 6.0)) self.assertTrue(outer.contains(inner)) self.assertFalse(inner.contains(outer)) self.assertFalse(outer.contains(disjoint)) def test_interior_contains_rect(self): outer = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(4.0, 4.0)) inner = s2.R2Rect(s2.R2Point(1.0, 1.0), s2.R2Point(3.0, 3.0)) same = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(4.0, 4.0)) self.assertTrue(outer.interior_contains(inner)) self.assertFalse(outer.interior_contains(same)) def test_intersects(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) r2 = s2.R2Rect(s2.R2Point(1.0, 1.0), s2.R2Point(3.0, 3.0)) r3 = s2.R2Rect(s2.R2Point(3.0, 3.0), s2.R2Point(4.0, 4.0)) self.assertTrue(r1.intersects(r2)) self.assertFalse(r1.intersects(r3)) def test_interior_intersects(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) r2 = s2.R2Rect(s2.R2Point(1.0, 1.0), s2.R2Point(3.0, 3.0)) touching = s2.R2Rect(s2.R2Point(2.0, 2.0), s2.R2Point(3.0, 3.0)) self.assertTrue(r1.interior_intersects(r2)) self.assertFalse(r1.interior_intersects(touching)) def test_add_point(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) rect.add_point(s2.R2Point(3.0, 3.0)) self.assertAlmostEqual(rect.hi.x, 3.0) self.assertAlmostEqual(rect.hi.y, 3.0) def test_add_rect(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) r2 = s2.R2Rect(s2.R2Point(2.0, 2.0), s2.R2Point(3.0, 3.0)) r1.add_rect(r2) self.assertAlmostEqual(r1.lo.x, 0.0) self.assertAlmostEqual(r1.lo.y, 0.0) self.assertAlmostEqual(r1.hi.x, 3.0) self.assertAlmostEqual(r1.hi.y, 3.0) def test_project(self): rect = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) # Point inside p = rect.project(s2.R2Point(1.0, 1.0)) self.assertEqual(p, s2.R2Point(1.0, 1.0)) # Point outside p = rect.project(s2.R2Point(5.0, 5.0)) self.assertEqual(p, s2.R2Point(2.0, 2.0)) # Point below p = rect.project(s2.R2Point(-1.0, -1.0)) self.assertEqual(p, s2.R2Point(0.0, 0.0)) def test_project_on_empty_raises(self): with self.assertRaises(ValueError): s2.R2Rect.empty().project(s2.R2Point(1.0, 1.0)) def test_expanded(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) expanded = rect.expanded(s2.R2Point(0.5, 1.0)) self.assertAlmostEqual(expanded.lo.x, 0.5) self.assertAlmostEqual(expanded.lo.y, 1.0) self.assertAlmostEqual(expanded.hi.x, 3.5) self.assertAlmostEqual(expanded.hi.y, 5.0) def test_union(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) r2 = s2.R2Rect(s2.R2Point(2.0, 2.0), s2.R2Point(3.0, 3.0)) union = r1.union(r2) self.assertAlmostEqual(union.lo.x, 0.0) self.assertAlmostEqual(union.lo.y, 0.0) self.assertAlmostEqual(union.hi.x, 3.0) self.assertAlmostEqual(union.hi.y, 3.0) def test_intersection(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) r2 = s2.R2Rect(s2.R2Point(1.0, 1.0), s2.R2Point(3.0, 3.0)) inter = r1.intersection(r2) self.assertAlmostEqual(inter.lo.x, 1.0) self.assertAlmostEqual(inter.lo.y, 1.0) self.assertAlmostEqual(inter.hi.x, 2.0) self.assertAlmostEqual(inter.hi.y, 2.0) def test_approx_equals(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) r2 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) r3 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0 + 1e-16)) r4 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.1)) self.assertTrue(r1.approx_equals(r2)) self.assertTrue(r1.approx_equals(r3)) self.assertFalse(r1.approx_equals(r4)) self.assertTrue(r1.approx_equals(r4, 0.2)) # Operators def test_equality(self): r1 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) r2 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) r3 = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(2.0, 2.0)) self.assertTrue(r1 == r2) self.assertTrue(r1 != r3) def test_empty_rects_are_equal(self): e1 = s2.R2Rect.empty() e2 = s2.R2Rect() self.assertTrue(e1 == e2) def test_hash(self): a = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) b = s2.R2Rect(s2.R2Point(0.0, 0.0), s2.R2Point(1.0, 1.0)) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_string_representation(self): rect = s2.R2Rect(s2.R2Point(1.0, 2.0), s2.R2Point(3.0, 4.0)) repr_str = repr(rect) str_str = str(rect) self.assertTrue(repr_str.startswith("R2Rect(")) # str should not have the class name prefix self.assertFalse(str_str.startswith("R2Rect(")) if __name__ == "__main__": unittest.main() src/python/s1angle_bindings.cc000066400000000000000000000157131524103652300167140ustar00rootroot00000000000000#include #include #include #include #include "absl/hash/hash.h" #include "absl/strings/str_cat.h" #include "s2/s1angle.h" #include "s2/s2point.h" namespace py = pybind11; namespace { void MaybeThrowNotNormalized(const S1Angle& angle) { if (!angle.IsNormalized()) { throw py::value_error( absl::StrCat("Angle ", angle.degrees(), " degrees is not in the normalized range (-180, 180]")); } } } // namespace void bind_s1angle(py::module& m) { py::class_(m, "S1Angle", "Represents a one-dimensional angle.\n\n" "The internal representation is a double-precision value in radians,\n" "so conversion to and from radians is exact. Conversions between\n" "degrees and radians are not always exact due to floating-point\n" "arithmetic (e.g. from_degrees(60).degrees != 60). Use e5/e6/e7\n" "representations for exact discrete comparisons.\n\n" "See s2/s1angle.h for comprehensive documentation including exact\n" "conversion guarantees and edge cases.") // Constructors .def(py::init<>(), "Default constructor creates a zero angle") .def(py::init(), py::arg("x"), py::arg("y"), "Construct the angle between two points.\n\n" "This is also equal to the distance between the points on the\n" "unit sphere. The points do not need to be normalized.") // Factory methods .def_static("from_radians", &S1Angle::Radians, py::arg("radians"), "Construct an angle from its measure in radians.\n\n" "This conversion is exact.") .def_static("from_degrees", &S1Angle::Degrees, py::arg("degrees"), "Construct an angle from its measure in degrees.\n\n" "Note: the round-trip from_degrees(x).degrees is not\n" "always exact. For example, from_degrees(60).degrees != 60.") .def_static("from_e5", &S1Angle::E5, py::arg("e5"), "Construct an angle from its E5 representation.\n\n" "E5 is degrees multiplied by 1e5 and rounded to the\n" "nearest integer.\n\n" "Note: E5 does not share the exact conversion guarantees\n" "of E6/E7. Avoid testing E5 values for exact equality\n" "with other formats.") .def_static("from_e6", &S1Angle::E6, py::arg("e6"), "Construct an angle from its E6 representation.\n\n" "E6 is degrees multiplied by 1e6 and rounded to the\n" "nearest integer.\n\n" "For any integer n: from_degrees(n) == from_e6(1000000 * n).") .def_static("from_e7", &S1Angle::E7, py::arg("e7"), "Construct an angle from its E7 representation.\n\n" "E7 is degrees multiplied by 1e7 and rounded to the\n" "nearest integer.\n\n" "For any integer n: from_degrees(n) == from_e7(10000000 * n).") .def_static("zero", &S1Angle::Zero, "Return a zero angle") .def_static("infinity", &S1Angle::Infinity, "Return an angle larger than any finite angle") // Properties .def_property_readonly("radians", &S1Angle::radians, "The angle in radians.\n\n" "This is the internal representation, so the conversion is exact.") .def_property_readonly("degrees", &S1Angle::degrees, "The angle in degrees.\n\n" "Note: from_degrees(x).degrees is not always exactly x due to\n" "the intermediate conversion to radians.") .def_property_readonly("e5", [](const S1Angle& self) { MaybeThrowNotNormalized(self); return self.e5(); }, "The E5 representation (degrees * 1e5, rounded).\n\n" "The angle must be in the normalized range (-180, 180] degrees.\n" "Raises ValueError if out of range.") .def_property_readonly("e6", [](const S1Angle& self) { MaybeThrowNotNormalized(self); return self.e6(); }, "The E6 representation (degrees * 1e6, rounded).\n\n" "The angle must be in the normalized range (-180, 180] degrees.\n" "Raises ValueError if out of range.") .def_property_readonly("e7", [](const S1Angle& self) { MaybeThrowNotNormalized(self); return self.e7(); }, "The E7 representation (degrees * 1e7, rounded).\n\n" "The angle must be in the normalized range (-180, 180] degrees.\n" "Raises ValueError if out of range.") // Predicates .def("is_normalized", &S1Angle::IsNormalized, "Return true if the angle is in the normalized range (-180, 180]") // Geometric operations .def("__abs__", &S1Angle::abs, "Return the absolute value of the angle") .def("normalized", &S1Angle::Normalized, "Return the angle normalized to the range (-180, 180] degrees") .def("normalize", &S1Angle::Normalize, "Normalize this angle in-place to the range (-180, 180] degrees") .def("sin", [](const S1Angle& self) { return sin(self); }, "Return the sine of the angle") .def("cos", [](const S1Angle& self) { return cos(self); }, "Return the cosine of the angle") .def("tan", [](const S1Angle& self) { return tan(self); }, "Return the tangent of the angle") // Operators .def(py::self == py::self, "Return true if angles are exactly equal") .def(py::self != py::self, "Return true if angles are not exactly equal") .def(py::self < py::self, "Return true if this angle is less than other") .def(py::self > py::self, "Return true if this angle is greater than other") .def(py::self <= py::self, "Return true if this angle is less than or equal to other") .def(py::self >= py::self, "Return true if this angle is greater than or equal to other") .def(-py::self, "Negate angle") .def(py::self + py::self, "Add two angles") .def(py::self - py::self, "Subtract two angles") .def(py::self * double(), "Multiply angle by scalar") .def("__rmul__", [](const S1Angle& self, double m) { return m * self; }, "Multiply angle by scalar (reversed operands)") .def(py::self / double(), "Divide angle by scalar") .def("__truediv__", [](const S1Angle& a, const S1Angle& b) -> double { return a / b; }, py::arg("other"), "Divide two angles, returning a scalar ratio") .def("__hash__", [](S1Angle self) { return absl::HashOf(self); }) // String representation .def("__repr__", [](S1Angle a) { std::ostringstream oss; oss << "S1Angle(" << a << ")"; return oss.str(); }) .def("__str__", [](S1Angle a) { std::ostringstream oss; oss << a; return oss.str(); }); } src/python/s1angle_test.py000066400000000000000000000226341524103652300161410ustar00rootroot00000000000000"""Tests for S1Angle pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS1Angle(unittest.TestCase): """Test cases for S1Angle bindings.""" # Constructors def test_default_constructor(self): a = s2.S1Angle() self.assertEqual(a.radians, 0.0) def test_constructor_from_two_points(self): x = s2.S2Point(1.0, 0.0, 0.0) y = s2.S2Point(0.0, 1.0, 0.0) a = s2.S1Angle(x, y) self.assertAlmostEqual(a.radians, math.pi / 2) def test_constructor_from_same_point(self): p = s2.S2Point(1.0, 0.0, 0.0) a = s2.S1Angle(p, p) self.assertEqual(a.radians, 0.0) def test_constructor_from_antipodal_points(self): x = s2.S2Point(1.0, 0.0, 0.0) y = s2.S2Point(-1.0, 0.0, 0.0) a = s2.S1Angle(x, y) self.assertAlmostEqual(a.radians, math.pi) # Factory methods def test_from_radians(self): a = s2.S1Angle.from_radians(math.pi / 4) self.assertAlmostEqual(a.radians, math.pi / 4) def test_from_degrees(self): a = s2.S1Angle.from_degrees(45.0) self.assertAlmostEqual(a.degrees, 45.0) def test_from_e5(self): a = s2.S1Angle.from_e5(4500000) self.assertAlmostEqual(a.degrees, 45.0) def test_from_e6(self): a = s2.S1Angle.from_e6(45000000) self.assertAlmostEqual(a.degrees, 45.0) def test_from_e7(self): a = s2.S1Angle.from_e7(450000000) self.assertAlmostEqual(a.degrees, 45.0) def test_zero(self): a = s2.S1Angle.zero() self.assertEqual(a.radians, 0.0) def test_infinity(self): a = s2.S1Angle.infinity() self.assertTrue(math.isinf(a.radians)) self.assertTrue(a.radians > 0) # Properties def test_radians(self): a = s2.S1Angle.from_radians(1.5) self.assertEqual(a.radians, 1.5) def test_degrees(self): a = s2.S1Angle.from_degrees(180.0) self.assertAlmostEqual(a.radians, math.pi) self.assertAlmostEqual(a.degrees, 180.0) def test_degrees_radians_conversion(self): # Exact conversions per the C++ header documentation. self.assertEqual(s2.S1Angle.from_degrees(180.0).radians, math.pi) for k in range(9): self.assertEqual( s2.S1Angle.from_degrees(45 * k).radians, k * math.pi / 4 ) def test_e5(self): a = s2.S1Angle.from_degrees(45.0) self.assertEqual(a.e5, 4500000) def test_e6(self): a = s2.S1Angle.from_degrees(45.0) self.assertEqual(a.e6, 45000000) def test_e7(self): a = s2.S1Angle.from_degrees(45.0) self.assertEqual(a.e7, 450000000) def test_e5_e6_e7_consistency(self): # Degrees(n) == E6(1000000 * n) == E7(10000000 * n) for integer n. for n in [0, 1, 45, 90, 180, -180, -90]: self.assertEqual( s2.S1Angle.from_degrees(n).radians, s2.S1Angle.from_e6(1000000 * n).radians, ) self.assertEqual( s2.S1Angle.from_degrees(n).radians, s2.S1Angle.from_e7(10000000 * n).radians, ) def test_properties_are_readonly(self): a = s2.S1Angle.from_degrees(45.0) with self.assertRaises(AttributeError): a.radians = 1.0 with self.assertRaises(AttributeError): a.degrees = 1.0 def test_e5_not_normalized_raises(self): a = s2.S1Angle.from_degrees(270.0) with self.assertRaises(ValueError): _ = a.e5 def test_e6_not_normalized_raises(self): a = s2.S1Angle.from_degrees(270.0) with self.assertRaises(ValueError): _ = a.e6 def test_e7_not_normalized_raises(self): a = s2.S1Angle.from_degrees(270.0) with self.assertRaises(ValueError): _ = a.e7 def test_e6_minus_180_not_normalized_raises(self): # -180 degrees is outside the normalized range (-180, 180]. a = s2.S1Angle.from_degrees(-180.0) with self.assertRaises(ValueError): _ = a.e6 def test_e6_plus_180_is_valid(self): # +180 degrees is inside the normalized range (-180, 180]. a = s2.S1Angle.from_degrees(180.0) self.assertEqual(a.e6, 180000000) # Predicates def test_is_normalized(self): self.assertTrue(s2.S1Angle.from_degrees(45.0).is_normalized()) self.assertTrue(s2.S1Angle.from_degrees(180.0).is_normalized()) self.assertFalse(s2.S1Angle.from_degrees(270.0).is_normalized()) self.assertFalse(s2.S1Angle.from_degrees(-180.0).is_normalized()) # Geometric operations def test_abs(self): pos = s2.S1Angle.from_degrees(45.0) neg = s2.S1Angle.from_degrees(-45.0) self.assertAlmostEqual(abs(pos).degrees, 45.0) self.assertAlmostEqual(abs(neg).degrees, 45.0) def test_abs_zero(self): a = s2.S1Angle.zero() self.assertEqual(abs(a).radians, 0.0) def test_normalized(self): a = s2.S1Angle.from_degrees(270.0) self.assertAlmostEqual(a.normalized().degrees, -90.0) def test_normalized_negative(self): a = s2.S1Angle.from_degrees(-270.0) self.assertAlmostEqual(a.normalized().degrees, 90.0) def test_normalized_minus_180_becomes_180(self): # Normalized range is (-180, 180]; -180 maps to 180. a = s2.S1Angle.from_degrees(-180.0) self.assertAlmostEqual(a.normalized().degrees, 180.0) def test_normalize_in_place(self): a = s2.S1Angle.from_degrees(270.0) a.normalize() self.assertAlmostEqual(a.degrees, -90.0) def test_sin(self): a = s2.S1Angle.from_degrees(90.0) self.assertAlmostEqual(a.sin(), 1.0) def test_cos(self): a = s2.S1Angle.from_degrees(0.0) self.assertAlmostEqual(a.cos(), 1.0) def test_tan(self): a = s2.S1Angle.from_degrees(45.0) self.assertAlmostEqual(a.tan(), 1.0) # Operators def test_equality(self): a = s2.S1Angle.from_degrees(45.0) b = s2.S1Angle.from_degrees(45.0) c = s2.S1Angle.from_degrees(90.0) self.assertTrue(a == b) self.assertTrue(a != c) self.assertFalse(a != b) self.assertFalse(a == c) def test_comparison(self): small = s2.S1Angle.from_degrees(10.0) large = s2.S1Angle.from_degrees(20.0) self.assertTrue(small < large) self.assertTrue(large > small) self.assertTrue(small <= large) self.assertTrue(large >= small) self.assertTrue(small <= small) self.assertTrue(small >= small) self.assertFalse(small > large) self.assertFalse(large < small) def test_negation(self): a = s2.S1Angle.from_degrees(45.0) neg = -a self.assertAlmostEqual(neg.degrees, -45.0) def test_addition(self): a = s2.S1Angle.from_degrees(30.0) b = s2.S1Angle.from_degrees(60.0) result = a + b self.assertAlmostEqual(result.degrees, 90.0) def test_subtraction(self): a = s2.S1Angle.from_degrees(90.0) b = s2.S1Angle.from_degrees(30.0) result = a - b self.assertAlmostEqual(result.degrees, 60.0) def test_scalar_multiplication(self): a = s2.S1Angle.from_degrees(45.0) result1 = a * 2.0 result2 = 2.0 * a self.assertAlmostEqual(result1.degrees, 90.0) self.assertAlmostEqual(result2.degrees, 90.0) def test_scalar_division(self): a = s2.S1Angle.from_degrees(90.0) result = a / 2.0 self.assertAlmostEqual(result.degrees, 45.0) def test_angle_division(self): a = s2.S1Angle.from_degrees(90.0) b = s2.S1Angle.from_degrees(45.0) ratio = a / b self.assertAlmostEqual(ratio, 2.0) def test_add_assign(self): a = s2.S1Angle.from_degrees(30.0) a += s2.S1Angle.from_degrees(60.0) self.assertAlmostEqual(a.degrees, 90.0) def test_sub_assign(self): a = s2.S1Angle.from_degrees(90.0) a -= s2.S1Angle.from_degrees(30.0) self.assertAlmostEqual(a.degrees, 60.0) def test_mul_assign(self): a = s2.S1Angle.from_degrees(45.0) a *= 2.0 self.assertAlmostEqual(a.degrees, 90.0) def test_div_assign(self): a = s2.S1Angle.from_degrees(90.0) a /= 2.0 self.assertAlmostEqual(a.degrees, 45.0) def test_hash(self): a = s2.S1Angle.from_degrees(45.0) b = s2.S1Angle.from_degrees(45.0) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_repr(self): # The repr format comes from C++ operator<< which uses %.7f on degrees. self.assertEqual( repr(s2.S1Angle.from_degrees(45.0)), "S1Angle(45.0000000)" ) self.assertEqual( repr(s2.S1Angle.from_degrees(45.00)), "S1Angle(45.0000000)" ) self.assertEqual( repr(s2.S1Angle.from_degrees(0.0)), "S1Angle(0.0000000)" ) self.assertEqual( repr(s2.S1Angle.from_degrees(-90.0)), "S1Angle(-90.0000000)" ) # Precision beyond 7 decimal places is truncated. self.assertEqual( repr(s2.S1Angle.from_degrees(45.0000000001)), "S1Angle(45.0000000)" ) def test_str(self): self.assertEqual(str(s2.S1Angle.from_degrees(45.0)), "45.0000000") self.assertEqual(str(s2.S1Angle.zero()), "0.0000000") if __name__ == "__main__": unittest.main() src/python/s1chord_angle_bindings.cc000066400000000000000000000207741524103652300200760ustar00rootroot00000000000000#include #include #include #include #include "absl/hash/hash.h" #include "absl/strings/str_cat.h" #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2point.h" #include "s2/s2pointutil.h" namespace py = pybind11; namespace { void MaybeThrowNotUnitLength(const S2Point& p, const char* name) { if (!S2::IsUnitLength(p)) { throw py::value_error( absl::StrCat(name, " must be a unit-length vector (norm=", p.Norm(), ")")); } } void MaybeThrowIfSpecial(const S1ChordAngle& a, const char* name) { if (a.is_special()) { throw py::value_error( absl::StrCat(name, " must not be a special value " "(negative() or infinity())")); } } } // namespace void bind_s1chord_angle(py::module& m) { py::class_(m, "S1ChordAngle", "Represents the angle subtended by a chord on the unit sphere.\n\n" "S1ChordAngle can represent angles between 0 and Pi radians. It is\n" "more efficient than S1Angle for computing and comparing distances,\n" "but loses some accuracy as the angle approaches Pi radians.\n\n" "See s2/s1chord_angle.h for comprehensive documentation, including\n" "accuracy analysis and guidance on when to prefer S1Angle.") // Constructors .def(py::init<>(), "Default constructor creates a zero chord angle") .def(py::init([](const S2Point& x, const S2Point& y) { MaybeThrowNotUnitLength(x, "x"); MaybeThrowNotUnitLength(y, "y"); return S1ChordAngle(x, y); }), py::arg("x"), py::arg("y"), "Construct the chord angle between two unit-length points.\n\n" "Raises ValueError if either point is not unit-length.") .def(py::init(), py::arg("angle"), "Construct from an S1Angle.\n\n" "Angles outside [0, Pi] are mapped as follows:\n" " Infinity() -> Infinity()\n" " negative -> Negative()\n" " > Pi -> Straight()\n" "This conversion is relatively expensive; prefer to convert at\n" "the boundaries of your algorithm.") // Factory methods .def_static("from_radians", &S1ChordAngle::Radians, py::arg("radians"), "Construct a chord angle from an angle in radians") .def_static("from_degrees", &S1ChordAngle::Degrees, py::arg("degrees"), "Construct a chord angle from an angle in degrees") .def_static("from_e5", &S1ChordAngle::E5, py::arg("e5"), "Construct a chord angle from the E5 representation") .def_static("from_e6", &S1ChordAngle::E6, py::arg("e6"), "Construct a chord angle from the E6 representation") .def_static("from_e7", &S1ChordAngle::E7, py::arg("e7"), "Construct a chord angle from the E7 representation") .def_static("zero", &S1ChordAngle::Zero, "Return the zero chord angle") .def_static("right", &S1ChordAngle::Right, "Return a 90-degree chord angle") .def_static("straight", &S1ChordAngle::Straight, "Return a 180-degree chord angle (the maximum finite value)") .def_static("infinity", &S1ChordAngle::Infinity, "Return a chord angle larger than any finite chord angle") .def_static("negative", &S1ChordAngle::Negative, "Return a chord angle smaller than Zero()") // Properties .def_property_readonly("radians", &S1ChordAngle::radians, "The angle in radians.\n\n" "Note: this performs a trigonometric conversion and should be\n" "avoided in inner loops.") .def_property_readonly("degrees", &S1ChordAngle::degrees, "The angle in degrees.\n\n" "Note: this performs a trigonometric conversion and should be\n" "avoided in inner loops.") .def_property_readonly("e5", [](const S1ChordAngle& self) { MaybeThrowIfSpecial(self, "self"); return self.e5(); }, "The E5 representation (degrees * 1e5, rounded).\n\n" "Raises ValueError if the angle is negative() or infinity().") .def_property_readonly("e6", [](const S1ChordAngle& self) { MaybeThrowIfSpecial(self, "self"); return self.e6(); }, "The E6 representation (degrees * 1e6, rounded).\n\n" "Raises ValueError if the angle is negative() or infinity().") .def_property_readonly("e7", [](const S1ChordAngle& self) { MaybeThrowIfSpecial(self, "self"); return self.e7(); }, "The E7 representation (degrees * 1e7, rounded).\n\n" "Raises ValueError if the angle is negative() or infinity().") // Predicates .def("is_zero", &S1ChordAngle::is_zero, "Return true if this is exactly zero") .def("is_negative", &S1ChordAngle::is_negative, "Return true if this is less than zero (e.g. Negative())") .def("is_infinity", &S1ChordAngle::is_infinity, "Return true if this is the Infinity() sentinel") .def("is_special", &S1ChordAngle::is_special, "Return true if this is Negative() or Infinity()") .def("is_valid", &S1ChordAngle::is_valid, "Return true if the internal representation is valid.\n\n" "Negative() and Infinity() are both considered valid.") // Geometric operations .def("to_angle", &S1ChordAngle::ToAngle, "Convert to an S1Angle.\n\n" "Infinity() converts to S1Angle::Infinity(); Negative() converts\n" "to an unspecified negative S1Angle. Uses trigonometric functions\n" "and should be avoided in inner loops.") .def("sin", [](const S1ChordAngle& self) { MaybeThrowIfSpecial(self, "self"); return sin(self); }, "Return the sine of the chord angle.\n\n" "More accurate and efficient than converting to S1Angle first.\n" "Raises ValueError if the angle is negative() or infinity().") .def("cos", [](const S1ChordAngle& self) { MaybeThrowIfSpecial(self, "self"); return cos(self); }, "Return the cosine of the chord angle.\n\n" "More accurate and efficient than converting to S1Angle first.\n" "Raises ValueError if the angle is negative() or infinity().") .def("tan", [](const S1ChordAngle& self) { MaybeThrowIfSpecial(self, "self"); return tan(self); }, "Return the tangent of the chord angle.\n\n" "More accurate and efficient than converting to S1Angle first.\n" "Raises ValueError if the angle is negative() or infinity().") // Operators .def(py::self == py::self, "Return true if chord angles are equal") .def(py::self != py::self, "Return true if chord angles are not equal") .def(py::self < py::self, "Return true if this is less than other (by length2)") .def(py::self > py::self, "Return true if this is greater than other (by length2)") .def(py::self <= py::self, "Return true if this is less than or equal to other") .def(py::self >= py::self, "Return true if this is greater than or equal to other") .def("__add__", [](const S1ChordAngle& a, const S1ChordAngle& b) { MaybeThrowIfSpecial(a, "left operand"); MaybeThrowIfSpecial(b, "right operand"); return a + b; }, py::is_operator(), "Add two chord angles, clamping the result to [0, Pi].\n\n" "Raises ValueError if either operand is Negative() or Infinity().") .def("__sub__", [](const S1ChordAngle& a, const S1ChordAngle& b) { MaybeThrowIfSpecial(a, "left operand"); MaybeThrowIfSpecial(b, "right operand"); return a - b; }, py::is_operator(), "Subtract two chord angles, clamping the result to [0, Pi].\n\n" "Raises ValueError if either operand is Negative() or Infinity().") .def("__hash__", [](const S1ChordAngle& self) { return absl::Hash()(self.length2()); }) // String representation .def("__repr__", [](const S1ChordAngle& a) { std::ostringstream oss; oss << "S1ChordAngle(" << a << ")"; return oss.str(); }) .def("__str__", [](const S1ChordAngle& a) { std::ostringstream oss; oss << a; return oss.str(); }); } src/python/s1chord_angle_test.py000066400000000000000000000224561524103652300173220ustar00rootroot00000000000000"""Tests for S1ChordAngle pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS1ChordAngle(unittest.TestCase): """Test cases for S1ChordAngle bindings.""" # Constructors def test_default_constructor(self): a = s2.S1ChordAngle() self.assertTrue(a.is_zero()) def test_constructor_from_two_points(self): x = s2.S2Point(1.0, 0.0, 0.0) y = s2.S2Point(0.0, 1.0, 0.0) a = s2.S1ChordAngle(x, y) self.assertAlmostEqual(a.radians, math.pi / 2) def test_constructor_from_same_point(self): p = s2.S2Point(1.0, 0.0, 0.0) a = s2.S1ChordAngle(p, p) self.assertTrue(a.is_zero()) def test_constructor_from_antipodal_points(self): x = s2.S2Point(1.0, 0.0, 0.0) y = s2.S2Point(-1.0, 0.0, 0.0) a = s2.S1ChordAngle(x, y) self.assertEqual(a, s2.S1ChordAngle.straight()) def test_constructor_non_unit_length_raises(self): bad = s2.S2Point(2.0, 0.0, 0.0) ok = s2.S2Point(1.0, 0.0, 0.0) with self.assertRaises(ValueError): s2.S1ChordAngle(bad, ok) with self.assertRaises(ValueError): s2.S1ChordAngle(ok, bad) def test_constructor_from_s1_angle(self): angle = s2.S1Angle.from_degrees(90.0) a = s2.S1ChordAngle(angle) self.assertAlmostEqual(a.radians, math.pi / 2) def test_constructor_from_s1_angle_negative(self): a = s2.S1ChordAngle(s2.S1Angle.from_radians(-1.0)) self.assertTrue(a.is_negative()) def test_constructor_from_s1_angle_infinity(self): a = s2.S1ChordAngle(s2.S1Angle.infinity()) self.assertTrue(a.is_infinity()) def test_constructor_from_s1_angle_larger_than_pi_clamps(self): a = s2.S1ChordAngle(s2.S1Angle.from_radians(math.pi + 1.0)) self.assertEqual(a, s2.S1ChordAngle.straight()) # Factory methods def test_from_radians(self): a = s2.S1ChordAngle.from_radians(math.pi / 2) self.assertAlmostEqual(a.radians, math.pi / 2) def test_from_degrees(self): a = s2.S1ChordAngle.from_degrees(90.0) self.assertAlmostEqual(a.degrees, 90.0) def test_zero(self): a = s2.S1ChordAngle.zero() self.assertTrue(a.is_zero()) def test_right(self): a = s2.S1ChordAngle.right() self.assertAlmostEqual(a.radians, math.pi / 2) def test_straight(self): a = s2.S1ChordAngle.straight() self.assertAlmostEqual(a.radians, math.pi) def test_infinity(self): a = s2.S1ChordAngle.infinity() self.assertTrue(a.is_infinity()) self.assertTrue(a.is_special()) def test_negative(self): a = s2.S1ChordAngle.negative() self.assertTrue(a.is_negative()) self.assertTrue(a.is_special()) # Properties def test_radians(self): a = s2.S1ChordAngle.from_radians(1.0) self.assertAlmostEqual(a.radians, 1.0) def test_degrees(self): a = s2.S1ChordAngle.from_degrees(45.0) self.assertAlmostEqual(a.degrees, 45.0) def test_e5_e6_e7(self): a = s2.S1ChordAngle.from_degrees(45.0) self.assertEqual(a.e5, 4500000) self.assertEqual(a.e6, 45000000) self.assertEqual(a.e7, 450000000) def test_e5_e6_e7_special_raises(self): with self.assertRaises(ValueError): _ = s2.S1ChordAngle.negative().e5 with self.assertRaises(ValueError): _ = s2.S1ChordAngle.infinity().e5 with self.assertRaises(ValueError): _ = s2.S1ChordAngle.negative().e6 with self.assertRaises(ValueError): _ = s2.S1ChordAngle.infinity().e6 with self.assertRaises(ValueError): _ = s2.S1ChordAngle.negative().e7 with self.assertRaises(ValueError): _ = s2.S1ChordAngle.infinity().e7 # Predicates def test_is_zero(self): self.assertTrue(s2.S1ChordAngle.zero().is_zero()) self.assertFalse(s2.S1ChordAngle.right().is_zero()) def test_is_negative(self): self.assertTrue(s2.S1ChordAngle.negative().is_negative()) self.assertFalse(s2.S1ChordAngle.zero().is_negative()) def test_is_infinity(self): self.assertTrue(s2.S1ChordAngle.infinity().is_infinity()) self.assertFalse(s2.S1ChordAngle.straight().is_infinity()) def test_is_special(self): self.assertTrue(s2.S1ChordAngle.negative().is_special()) self.assertTrue(s2.S1ChordAngle.infinity().is_special()) self.assertFalse(s2.S1ChordAngle.zero().is_special()) self.assertFalse(s2.S1ChordAngle.straight().is_special()) def test_is_valid(self): self.assertTrue(s2.S1ChordAngle.zero().is_valid()) self.assertTrue(s2.S1ChordAngle.straight().is_valid()) self.assertTrue(s2.S1ChordAngle.negative().is_valid()) self.assertTrue(s2.S1ChordAngle.infinity().is_valid()) # Geometric operations def test_to_angle(self): a = s2.S1ChordAngle.from_degrees(90.0) angle = a.to_angle() self.assertAlmostEqual(angle.degrees, 90.0) def test_to_angle_special_values(self): self.assertEqual(s2.S1ChordAngle.infinity().to_angle(), s2.S1Angle.infinity()) self.assertTrue(s2.S1ChordAngle.negative().to_angle().radians < 0) def test_sin_cos_tan(self): a = s2.S1ChordAngle.from_degrees(30.0) self.assertAlmostEqual(a.sin(), 0.5, places=10) self.assertAlmostEqual(a.cos(), math.sqrt(3) / 2, places=10) self.assertAlmostEqual(a.tan(), 1.0 / math.sqrt(3), places=10) def test_sin_cos_tan_special_raises(self): with self.assertRaises(ValueError): s2.S1ChordAngle.negative().sin() with self.assertRaises(ValueError): s2.S1ChordAngle.infinity().sin() with self.assertRaises(ValueError): s2.S1ChordAngle.negative().cos() with self.assertRaises(ValueError): s2.S1ChordAngle.infinity().cos() with self.assertRaises(ValueError): s2.S1ChordAngle.negative().tan() with self.assertRaises(ValueError): s2.S1ChordAngle.infinity().tan() # Operators def test_equality(self): a = s2.S1ChordAngle.from_degrees(45.0) b = s2.S1ChordAngle.from_degrees(45.0) c = s2.S1ChordAngle.from_degrees(90.0) self.assertTrue(a == b) self.assertTrue(a != c) def test_comparison(self): a = s2.S1ChordAngle.from_degrees(30.0) b = s2.S1ChordAngle.from_degrees(60.0) self.assertTrue(a < b) self.assertTrue(b > a) self.assertTrue(a <= a) self.assertTrue(a >= a) def test_comparison_special_values(self): # Negative < Zero < finite < Infinity. neg = s2.S1ChordAngle.negative() zero = s2.S1ChordAngle.zero() finite = s2.S1ChordAngle.from_degrees(45.0) inf = s2.S1ChordAngle.infinity() self.assertLess(neg, zero) self.assertLess(zero, finite) self.assertLess(finite, inf) def test_add(self): a = s2.S1ChordAngle.from_degrees(30.0) b = s2.S1ChordAngle.from_degrees(60.0) total = a + b self.assertAlmostEqual(total.degrees, 90.0, places=5) def test_add_clamps_to_pi(self): a = s2.S1ChordAngle.from_degrees(120.0) b = s2.S1ChordAngle.from_degrees(120.0) total = a + b self.assertEqual(total, s2.S1ChordAngle.straight()) def test_add_special_raises(self): a = s2.S1ChordAngle.from_degrees(30.0) with self.assertRaises(ValueError): _ = a + s2.S1ChordAngle.negative() with self.assertRaises(ValueError): _ = s2.S1ChordAngle.infinity() + a def test_sub(self): a = s2.S1ChordAngle.from_degrees(60.0) b = s2.S1ChordAngle.from_degrees(30.0) diff = a - b self.assertAlmostEqual(diff.degrees, 30.0, places=5) def test_sub_clamps_at_zero(self): a = s2.S1ChordAngle.from_degrees(30.0) b = s2.S1ChordAngle.from_degrees(60.0) diff = a - b self.assertTrue(diff.is_zero()) def test_sub_special_raises(self): a = s2.S1ChordAngle.from_degrees(30.0) with self.assertRaises(ValueError): _ = a - s2.S1ChordAngle.negative() def test_add_assign(self): a = s2.S1ChordAngle.from_degrees(30.0) a += s2.S1ChordAngle.from_degrees(60.0) self.assertAlmostEqual(a.degrees, 90.0, places=5) def test_sub_assign(self): a = s2.S1ChordAngle.from_degrees(60.0) a -= s2.S1ChordAngle.from_degrees(30.0) self.assertAlmostEqual(a.degrees, 30.0, places=5) def test_hash(self): a = s2.S1ChordAngle.from_degrees(45.0) b = s2.S1ChordAngle.from_degrees(45.0) self.assertEqual(hash(a), hash(b)) s = {a, b} self.assertEqual(len(s), 1) # String representation def test_repr(self): a = s2.S1ChordAngle.from_degrees(90.0) self.assertEqual(repr(a), "S1ChordAngle(90.0000000)") def test_str(self): a = s2.S1ChordAngle.from_degrees(90.0) self.assertEqual(str(a), "90.0000000") def test_str_negative_sentinel(self): # negative() is a sentinel value; its string output is implementation- # defined but should represent a negative angle. self.assertIn("-", str(s2.S1ChordAngle.negative())) if __name__ == "__main__": unittest.main() src/python/s1interval_bindings.cc000066400000000000000000000157751524103652300174620ustar00rootroot00000000000000#include #include #include "absl/hash/hash.h" #include "absl/strings/str_cat.h" #include "s2/s1interval.h" namespace py = pybind11; namespace { void MaybeThrowInvalidPoint(double p) { if (!S1Interval::IsValidPoint(p)) { throw py::value_error(absl::StrCat("Invalid S1 point: ", p)); } } } // namespace void bind_s1interval(py::module& m) { py::class_(m, "S1Interval") // Constructors .def(py::init<>(), "Default constructor creates an empty interval") .def(py::init([](double lo, double hi) { MaybeThrowInvalidPoint(lo); MaybeThrowInvalidPoint(hi); return S1Interval(lo, hi); }), py::arg("lo"), py::arg("hi"), "Constructor that accepts the endpoints of the interval.\n\n" "Both endpoints must be in the range -Pi to Pi inclusive.\n" "Raises ValueError if either bound is outside that range.") // Static factory methods .def_static("empty", &S1Interval::Empty, "Returns the empty interval") .def_static("full", &S1Interval::Full, "Returns the full interval") .def_static("from_point", &S1Interval::FromPoint, py::arg("p"), "Constructs an interval containing a single point") .def_static("from_point_pair", [](double p1, double p2) { MaybeThrowInvalidPoint(p1); MaybeThrowInvalidPoint(p2); return S1Interval::FromPointPair(p1, p2); }, py::arg("p1"), py::arg("p2"), "Constructs the minimal interval containing two points") // Properties .def_property_readonly("lo", &S1Interval::lo, "Lower bound") .def_property_readonly("hi", &S1Interval::hi, "Upper bound") .def("bounds", [](const S1Interval& self) { return py::make_tuple(self.lo(), self.hi()); }, "Return bounds as a tuple (lo, hi)") // Predicates .def("is_full", &S1Interval::is_full, "Return true if the interval contains all points on the unit circle") .def("is_empty", &S1Interval::is_empty, "Return true if the interval is empty, i.e. it contains no points") .def("is_inverted", &S1Interval::is_inverted, "Return true if lo() > hi(). (This is true for empty intervals.)") // Geometric operations .def("center", &S1Interval::GetCenter, "Return the midpoint of the interval.\n\n" "For full and empty intervals, the result is arbitrary.") .def("length", &S1Interval::GetLength, "Return the length of the interval.\n\n" "The length of an empty interval is negative.") .def("complement_center", &S1Interval::GetComplementCenter, "Return the midpoint of the complement of the interval.\n\n" "For full and empty intervals, the result is arbitrary. For a\n" "singleton interval, the result is its antipodal point on S1.") .def("contains_point", [](const S1Interval& self, double p) { MaybeThrowInvalidPoint(p); return self.Contains(p); }, py::arg("p"), "Return true if the interval (which is closed) contains the point 'p'") .def("interior_contains_point", [](const S1Interval& self, double p) { MaybeThrowInvalidPoint(p); return self.InteriorContains(p); }, py::arg("p"), "Return true if the interior of the interval contains the point 'p'") .def("contains", py::overload_cast( &S1Interval::Contains, py::const_), py::arg("other"), "Return true if the interval contains the given interval 'y'") .def("interior_contains", py::overload_cast( &S1Interval::InteriorContains, py::const_), py::arg("other"), "Return true if the interior of this interval contains the entire interval 'y'") .def("intersects", &S1Interval::Intersects, py::arg("other"), "Return true if the two intervals contain any points in common") .def("interior_intersects", &S1Interval::InteriorIntersects, py::arg("other"), "Return true if the interior of this interval contains any point of 'y'") .def("add_point", [](S1Interval& self, double p) { MaybeThrowInvalidPoint(p); self.AddPoint(p); }, py::arg("p"), "Expand the interval to contain the given point 'p'.\n\n" "The point should be an angle in the range [-Pi, Pi].") .def("project", [](const S1Interval& self, double p) { if (self.is_empty()) throw py::value_error("Invalid S1Interval"); MaybeThrowInvalidPoint(p); return self.Project(p); }, py::arg("p"), "Return the closest point in the interval to 'p'.\n\n" "The interval must be non-empty.") .def("expanded", &S1Interval::Expanded, py::arg("margin"), "Return interval expanded on each side by 'margin' (radians).\n\n" "If 'margin' is negative, shrink the interval instead. The resulting\n" "interval may be empty or full. Any expansion of a full interval remains\n" "full, and any expansion of an empty interval remains empty.") .def("union", &S1Interval::Union, py::arg("other"), "Return the smallest interval containing this interval and 'y'") .def("intersection", &S1Interval::Intersection, py::arg("other"), "Return the smallest interval containing the intersection with 'y'.\n\n" "Note that the region of intersection may consist of two disjoint intervals.") .def("complement", &S1Interval::Complement, "Return the complement of the interior of the interval") .def("directed_hausdorff_distance", &S1Interval::GetDirectedHausdorffDistance, py::arg("other"), "Return the directed Hausdorff distance to 'y'") // Note: default value must match C++ signature in s1interval.h .def("approx_equals", &S1Interval::ApproxEquals, py::arg("other"), py::arg("max_error") = 1e-15, "Return true if approximately equal to 'y'.\n\n" "Two intervals are approximately equal if each endpoint can be moved\n" "by at most 'max_error' (radians) to match the other interval.") // Operators .def(py::self == py::self, "Return true if two intervals contain the same set of points") .def(py::self != py::self, "Return true if two intervals do not contain the same set of points") .def("__hash__", [](const S1Interval& self) { return absl::HashOf(self); }) // String representation .def("__repr__", [](const S1Interval& i) { std::ostringstream oss; oss << "S1Interval(" << i << ")"; return oss.str(); }) .def("__str__", [](const S1Interval& i) { std::ostringstream oss; oss << i; return oss.str(); }); } src/python/s1interval_test.py000066400000000000000000000242641524103652300167000ustar00rootroot00000000000000"""Tests for S1Interval pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS1Interval(unittest.TestCase): """Test cases for S1Interval bindings.""" # Constructors def test_default_constructor(self): interval = s2.S1Interval() self.assertTrue(interval.is_empty()) def test_constructor_with_bounds(self): interval = s2.S1Interval(0.0, math.pi / 2) self.assertAlmostEqual(interval.lo, 0.0) self.assertAlmostEqual(interval.hi, math.pi / 2) self.assertFalse(interval.is_empty()) def test_constructor_converts_minus_pi_to_pi(self): # "The value -π is converted internally to π except for the Full() and Empty() intervals" # (from s1interval.h constructor documentation) interval = s2.S1Interval(-math.pi, 0.0) self.assertEqual(interval.lo, math.pi) # -π converted to π self.assertEqual(interval.hi, 0.0) self.assertTrue(interval.is_inverted()) # Static factory methods def test_empty_constructor(self): empty = s2.S1Interval.empty() self.assertTrue(empty.is_empty()) def test_full_constructor(self): full = s2.S1Interval.full() self.assertTrue(full.is_full()) def test_from_point(self): point_interval = s2.S1Interval.from_point(1.0) self.assertEqual(point_interval.lo, 1.0) self.assertEqual(point_interval.hi, 1.0) def test_from_point_pair(self): pair_interval = s2.S1Interval.from_point_pair(0.5, 2.0) self.assertTrue(pair_interval.contains_point(1.0)) def test_from_point_pair_invalid_raises(self): with self.assertRaises(ValueError): s2.S1Interval.from_point_pair(0.5, 4.0) # 4.0 > π with self.assertRaises(ValueError): s2.S1Interval.from_point_pair(-4.0, 0.5) # -4.0 < -π # Properties def test_properties_lo_hi(self): interval = s2.S1Interval(0.0, math.pi / 2) self.assertAlmostEqual(interval.lo, 0.0) self.assertAlmostEqual(interval.hi, math.pi / 2) def test_lo_hi_are_readonly(self): interval = s2.S1Interval(0.0, math.pi / 2) with self.assertRaises(AttributeError): interval.lo = 0.5 with self.assertRaises(AttributeError): interval.hi = 0.5 def test_bounds(self): interval = s2.S1Interval(0.5, 2.0) bounds = interval.bounds() self.assertEqual(bounds, (0.5, 2.0)) self.assertAlmostEqual(bounds[0], interval.lo) self.assertAlmostEqual(bounds[1], interval.hi) # Predicates def test_invalid_bounds_too_large(self): with self.assertRaises(ValueError): s2.S1Interval(0.0, 4.0) # 4.0 > π def test_invalid_bounds_too_small(self): with self.assertRaises(ValueError): s2.S1Interval(-4.0, 0.0) # -4.0 < -π def test_invalid_both_bounds_out_of_range(self): with self.assertRaises(ValueError): s2.S1Interval(-4.0, 4.0) def test_is_full_and_empty(self): empty = s2.S1Interval.empty() self.assertTrue(empty.is_empty()) self.assertFalse(empty.is_full()) full = s2.S1Interval.full() self.assertTrue(full.is_full()) self.assertFalse(full.is_empty()) normal = s2.S1Interval(0.0, math.pi) self.assertFalse(normal.is_empty()) self.assertFalse(normal.is_full()) def test_is_inverted(self): # Normal interval normal = s2.S1Interval(0.0, math.pi) self.assertFalse(normal.is_inverted()) # Inverted interval (wraps around) inverted = s2.S1Interval(math.pi, 0.0) self.assertTrue(inverted.is_inverted()) # Geometric operations def test_center(self): interval = s2.S1Interval(0.0, math.pi) self.assertAlmostEqual(interval.center(), math.pi / 2) def test_length(self): interval = s2.S1Interval(0.0, math.pi) self.assertAlmostEqual(interval.length(), math.pi) def test_complement_center(self): interval = s2.S1Interval(0.0, math.pi / 2) complement_center = interval.complement_center() self.assertIsNotNone(complement_center) def test_contains_point(self): interval = s2.S1Interval(0.0, math.pi) self.assertTrue(interval.contains_point(math.pi / 2)) self.assertTrue(interval.contains_point(0.0)) self.assertTrue(interval.contains_point(math.pi)) self.assertFalse(interval.contains_point(-math.pi / 2)) def test_contains_point_invalid_raises(self): interval = s2.S1Interval(0.0, math.pi) with self.assertRaises(ValueError): interval.contains_point(4.0) # 4.0 > π def test_interior_contains_point(self): interval = s2.S1Interval(0.0, math.pi) self.assertTrue(interval.interior_contains_point(math.pi / 2)) self.assertFalse(interval.interior_contains_point(0.0)) self.assertFalse(interval.interior_contains_point(math.pi)) def test_interior_contains_point_invalid_raises(self): interval = s2.S1Interval(0.0, math.pi) with self.assertRaises(ValueError): interval.interior_contains_point(4.0) # 4.0 > π def test_contains_interval(self): interval1 = s2.S1Interval(0.0, math.pi) interval2 = s2.S1Interval(0.5, 2.0) interval3 = s2.S1Interval(-math.pi, -2.0) self.assertTrue(interval1.contains(interval2)) self.assertFalse(interval1.contains(interval3)) def test_interior_contains_interval(self): interval1 = s2.S1Interval(0.0, math.pi) interval2 = s2.S1Interval(0.5, 2.0) self.assertTrue(interval1.interior_contains(interval2)) def test_intersects(self): interval1 = s2.S1Interval(0.0, 2.0) interval2 = s2.S1Interval(1.0, 3.0) interval3 = s2.S1Interval(-3.0, -2.5) self.assertTrue(interval1.intersects(interval2)) self.assertFalse(interval1.intersects(interval3)) def test_interior_intersects(self): interval1 = s2.S1Interval(0.0, 2.0) interval2 = s2.S1Interval(1.0, 3.0) interval3 = s2.S1Interval(-3.0, -2.5) self.assertTrue(interval1.interior_intersects(interval2)) self.assertFalse(interval1.interior_intersects(interval3)) def test_add_point(self): interval = s2.S1Interval(0.0, 1.0) interval.add_point(1.5) self.assertTrue(interval.contains_point(1.5)) def test_add_point_invalid_raises(self): interval = s2.S1Interval(0.0, 1.0) with self.assertRaises(ValueError): interval.add_point(4.0) # 4.0 > π def test_project(self): interval = s2.S1Interval(0.0, 1.5) # Point inside interval self.assertAlmostEqual(interval.project(1.0), 1.0) def test_project_on_empty_raises(self): with self.assertRaises(ValueError): s2.S1Interval.empty().project(1.0) def test_project_invalid_point_raises(self): interval = s2.S1Interval(0.0, 1.5) with self.assertRaises(ValueError): interval.project(4.0) # 4.0 > π def test_expanded(self): interval = s2.S1Interval(0.5, 1.5) expanded = interval.expanded(0.5) self.assertAlmostEqual(expanded.length(), interval.length() + 1.0) def test_union(self): interval1 = s2.S1Interval(0.0, 1.0) interval2 = s2.S1Interval(0.5, 1.5) union = interval1.union(interval2) self.assertTrue(union.contains_point(0.5)) self.assertTrue(union.contains_point(1.2)) def test_intersection(self): interval1 = s2.S1Interval(0.0, 2.0) interval2 = s2.S1Interval(1.0, 3.0) intersection = interval1.intersection(interval2) self.assertAlmostEqual(intersection.lo, 1.0) self.assertAlmostEqual(intersection.hi, 2.0) def test_complement(self): interval = s2.S1Interval(0.0, math.pi / 2) complement = interval.complement() self.assertTrue(complement.is_inverted()) self.assertFalse(complement.contains_point(math.pi / 4)) self.assertTrue(complement.contains_point(math.pi)) def test_directed_hausdorff_distance(self): interval1 = s2.S1Interval(0.0, 1.0) interval2 = s2.S1Interval(0.5, 1.5) distance = interval1.directed_hausdorff_distance(interval2) self.assertIsNotNone(distance) def test_approx_equals(self): interval1 = s2.S1Interval(0.0, 2.0) interval2 = s2.S1Interval(0.0, 2.0) interval3 = s2.S1Interval(0.0, 2.0 + 1e-16) # Very small difference interval4 = s2.S1Interval(0.0, 2.1) # Larger difference # Test with default max_error (1e-15) self.assertTrue(interval1.approx_equals(interval2)) # Within default tolerance self.assertTrue(interval1.approx_equals(interval3)) # Outside default tolerance self.assertFalse(interval1.approx_equals(interval4)) # Test with explicit max_error values self.assertTrue(interval1.approx_equals(interval3, 1e-15)) self.assertFalse(interval1.approx_equals(interval4, 0.05)) self.assertTrue(interval1.approx_equals(interval4, 0.2)) # Operators def test_equality(self): interval1 = s2.S1Interval(0.0, 2.0) interval2 = s2.S1Interval(0.0, 2.0) interval3 = s2.S1Interval(0.0, 3.0) self.assertTrue(interval1 == interval2) self.assertTrue(interval1 != interval3) def test_hash(self): a = s2.S1Interval(0.0, 1.0) b = s2.S1Interval(0.0, 1.0) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_string_representation(self): interval = s2.S1Interval(0.0, 2.0) self.assertEqual(repr(interval), "S1Interval([0, 2])") self.assertEqual(str(interval), "[0, 2]") empty = s2.S1Interval.empty() # Empty interval has lo=pi, hi=-pi self.assertEqual(repr(empty), "S1Interval([3.14159, -3.14159])") self.assertEqual(str(empty), "[3.14159, -3.14159]") full = s2.S1Interval.full() # Full interval spans from -pi to pi self.assertEqual(repr(full), "S1Interval([-3.14159, 3.14159])") self.assertEqual(str(full), "[-3.14159, 3.14159]") if __name__ == "__main__": unittest.main() src/python/s2.i000066400000000000000000000027511524103652300136720ustar00rootroot00000000000000%include "std_vector.i" %include "std_string.i" %include "stdint.i" %{ #include "absl/strings/string_view.h" %} %typemap(typecheck) absl::string_view = char *; %typemap(in) absl::string_view { if ($input != Py_None) { Py_ssize_t len; if (PyUnicode_Check($input)) { const char *buf; buf = PyUnicode_AsUTF8AndSize($input, &len); if (buf == nullptr) { SWIG_fail; } $1 = absl::string_view(buf, len); } else { char *buf; if (PyBytes_AsStringAndSize($input, &buf, &len) == -1) { // Python has raised an error (likely TypeError or UnicodeEncodeError). SWIG_fail; } $1 = absl::string_view(buf, len); } } } %template() std::vector; %template() std::vector; %template() std::vector; %template() std::vector; %template() std::vector; // Standard Google convention is to ignore all functions and methods, and // selectively add back those for which wrapping is both required and // functional. %define %ignoreall %ignore ""; %enddef %define %unignore %rename("%s") %enddef %define %unignoreall %rename("%s") ""; %enddef %define ABSL_ATTRIBUTE_ALWAYS_INLINE %enddef %define ABSL_DEPRECATE_AND_INLINE(msg) %enddef %define ABSL_DEPRECATED(msg) %enddef %define absl_nonnull %enddef %define absl_nullable %enddef // TODO: Remove when Ubuntu 22 is unsupported, ~2027-05-01. #if SWIG_VERSION < 0x042000 %define final %enddef #endif %include "coder.i" %include "s2_common.i" src/python/s2_common.i000077500000000000000000001017641524103652300152510ustar00rootroot00000000000000// Copyright 2006 Google Inc. All Rights Reserved. // These SWIG definitions are shared between the internal Google and external // open source releases of s2. %{ #include #include #include #include "s2/s2boolean_operation.h" #include "s2/s2buffer_operation.h" #include "s2/s2builder.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_s2polygon_layer.h" #include "s2/s2cell_id.h" #include "s2/s2region.h" #include "s2/s2cap.h" #include "s2/s2edge_crossings.h" #include "s2/s2edge_distances.h" #include "s2/s2earth.h" #include "s2/s2latlng.h" #include "s2/s2latlng_rect.h" #include "s2/s2loop.h" #include "s2/s2measures.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2predicates.h" #include "s2/s2region_coverer.h" #include "s2/s2region_term_indexer.h" #include "s2/s2cell.h" #include "s2/s2cell_union.h" #include "s2/s2shape_index.h" #include "s2/mutable_s2shape_index.h" // Wrapper for S2BufferOperation::Options to work around the inability // to handle nested classes in SWIG. class S2BufferOperationOptions { public: S2BufferOperation::Options opts; void set_buffer_radius(S1Angle buffer_radius) { opts.set_buffer_radius(buffer_radius); } void set_error_fraction(double error_fraction) { opts.set_error_fraction(error_fraction); } }; // Wrapper for S2PolygonLayer::Options to work around the inability to // handle nested classes in SWIG. class S2PolygonLayerOptions { public: s2builderutil::S2PolygonLayer::Options opts; void set_edge_type(S2Builder::EdgeType edge_type) { opts.set_edge_type(edge_type); } }; %} %inline %{ static PyObject *FromS2CellId(const S2CellId &cell_id) { return SWIG_NewPointerObj(new S2CellId(cell_id), SWIGTYPE_p_S2CellId, SWIG_POINTER_OWN); } %} %apply std::vector *OUTPUT {std::vector *covering}; %apply std::vector *OUTPUT {std::vector *interior}; %apply std::vector *OUTPUT {std::vector *output}; %typemap(in, numinputs=0) S2CellId *OUTPUT_ARRAY_4(S2CellId temp[4]) { $1 = temp; } // For S2Polygon::GetOverlapFractions %typemap(out) std::pair { $result = Py_BuildValue("dd", $1.first, $1.second); } %typemap(argout) S2CellId *OUTPUT_ARRAY_4 { $result = PyList_New(4); if ($result == nullptr) return nullptr; for (int i = 0; i < 4; i++) { PyObject *const o = FromS2CellId($1[i]); if (!o) { Py_DECREF($result); return nullptr; } PyList_SET_ITEM($result, i, o); } } %apply S2CellId *OUTPUT_ARRAY_4 {S2CellId neighbors[4]}; // Convert an S2Error into a Python exception. This requires two // typemaps: the first declares a local variable of type S2Error and // passes a pointer to it into the called function, and the second // inspects the S2Error variable after the call and throws an // exception if its ok() method returns false. %typemap(in, numinputs=0) S2Error * (S2Error err) { $1 = &err; } %typemap(argout) S2Error * { if(!$1->ok()) SWIG_exception(SWIG_ValueError, std::string($1->message()).c_str()); } // This overload shadows the one the takes vector&, and it // does not work anyway. %ignore S2CellUnion::Init(std::vector const& cell_ids); // The SWIG code which picks between overloaded methods doesn't work // when given a list parameter. SWIG_Python_ConvertPtrAndOwn calls // SWIG_Python_GetSwigThis, doesn't find the 'this' attribute and gives up. // To avoid this problem rename the Polyline::Init methods so they aren't // overloaded. We also need to reimplement them since SWIG doesn't // seem to understand absl::Span. %extend S2Polyline { public: void InitFromS2LatLngs(const std::vector& vertices) { $self->Init(absl::MakeConstSpan(vertices)); } void InitFromS2Points(const std::vector& vertices) { $self->Init(absl::MakeConstSpan(vertices)); } }; // And similarly for the overloaded S2CellUnion::Normalize method. %rename(NormalizeS2CellUnion) S2CellUnion::Normalize(); %apply int *OUTPUT {int *next_vertex}; %apply int *OUTPUT {int *psi}; %apply int *OUTPUT {int *pti}; %apply int *OUTPUT {int *pi}; %apply int *OUTPUT {int *pj}; %apply int *OUTPUT {int *orientation}; %apply SWIGTYPE *DISOWN {S2Loop *loop_disown}; %apply SWIGTYPE *DISOWN {S2Builder::Layer *layer_disown}; %apply SWIGTYPE *DISOWN {S2Polygon *polygon_disown}; %typemap(in) std::vector * (std::vector loops) { PyObject *iter = PyObject_GetIter($input); if (iter == nullptr) { %argument_fail(SWIG_TypeError, "iterable of S2Loop *", $symname, $argnum); } for (PyObject *elem; (elem = PyIter_Next(iter)); Py_DECREF(elem)) { S2Loop *loop = nullptr; int res = SWIG_ConvertPtr( elem, reinterpret_cast(&loop), $descriptor(S2Loop *), SWIG_POINTER_NO_NULL); if (!SWIG_IsOK(res)) { Py_DECREF(elem); Py_DECREF(iter); for (S2Loop *loop : loops) delete loop; %argument_fail(res, "$type", $symname, $argnum); } loops.push_back(new S2Loop(*loop)); } Py_DECREF(iter); $1 = &loops; } %typemap(in, numinputs=0) std::vector *out(std::vector temp) { $1 = &temp; } %typemap(argout) std::vector *out { $result = PyList_New($1->size()); if ($result == nullptr) return nullptr; for (int i = 0; i < $1->size(); i++) { PyObject *const o = SWIG_NewPointerObj((*$1)[i], $descriptor(S2Polyline *), SWIG_POINTER_OWN); if (!o) { Py_DECREF($result); return nullptr; } PyList_SET_ITEM($result, i, o); } } %inline %{ // This isn't a constructor because it clashes with the SWIG-redefinition // below and the actual S2Point (a Vector_3d). static PyObject *S2Point_FromRaw(double x, double y, double z) { // Creates an S2Point directly, mostly useful for testing. return SWIG_NewPointerObj(new S2Point(x, y, z), SWIGTYPE_p_S2Point, SWIG_POINTER_OWN); } static PyObject *S2Point_ToRaw(const S2Point& p) { return Py_BuildValue("ddd", p[0], p[1], p[2]); } %} // We provide our own definition of S2Point, because the real one is too // difficult to wrap correctly. class S2Point { public: double x(); double y(); double z(); double Norm(); S2Point Normalize(); ~S2Point(); }; // The extensions below exist because of the difficulty swigging S2Point. // This alternate method of S2Loop::vertex() returns a S2LatLng instead. %extend S2Loop { public: S2LatLng GetS2LatLngVertex(int i) { return S2LatLng($self->vertex(i)); } }; // This alternate method of S2Cell::GetVertex() returns a S2LatLng instead. %extend S2Cell { public: S2LatLng GetS2LatLngVertex(int k) { return S2LatLng($self->GetVertex(k)); } }; // This alternate method of S2Cell::GetEdge() returns a S2LatLng instead. %extend S2Cell { public: S2LatLng GetS2LatLngEdge(int k) { return S2LatLng($self->GetEdge(k)); } }; // The extensions below exist to work around the use of absl::Span. %extend S2Loop { public: explicit S2Loop(const std::vector& vertices) { return new S2Loop(absl::MakeConstSpan(vertices)); } void Init(const std::vector& vertices) { $self->Init(absl::MakeConstSpan(vertices)); } }; // Add raw pointer versions of these functions because SWIG doesn't // understand unique_ptr and when std::move() must be used. // TODO(user): Make swig understand unique_ptr and vector. %extend S2Polygon { public: // Takes ownership of the loop. The _disown suffix is used to tell SWIG // that S2Polygon takes ownership of the loop. explicit S2Polygon(S2Loop* loop_disown) { // SWIG recognizes this as a constructor, but implements this // as a free function, so write it that way. return new S2Polygon(std::unique_ptr(loop_disown)); } void InitNested(std::vector* loops) { std::vector> unique_loops(loops->size()); for (int i = 0; i < loops->size(); ++i) { unique_loops[i].reset((*loops)[i]); } loops->clear(); $self->InitNested(std::move(unique_loops)); } void IntersectWithPolyline(S2Polyline const* in, std::vector* out) const { std::vector> polylines = $self->IntersectWithPolyline(*in); ABSL_DCHECK(out->empty()); out->reserve(polylines.size()); for (auto& polyline : polylines) { out->push_back(polyline.release()); } } } %extend S2Builder { public: void StartLayer(S2Builder::Layer* layer_disown) { $self->StartLayer(std::unique_ptr(layer_disown)); } } class S2PolygonLayerOptions { public: s2builderutil::S2PolygonLayer::Options opts; void set_edge_type(S2Builder::EdgeType); }; // S2PolygonLayer's constructor takes a pointer to an S2Polygon. We // need to ensure that the S2Polygon is not destroyed while the // S2PolygonLayer still references it. To do this, save a reference to // the polygon in the Python wrapper object. %pythonprepend s2builderutil::S2PolygonLayer::S2PolygonLayer %{ self._incref = args[0] %} %extend s2builderutil::S2PolygonLayer { public: S2PolygonLayer(S2Polygon* layer, const S2PolygonLayerOptions& options) { return new s2builderutil::S2PolygonLayer(layer, options.opts); } } %extend MutableS2ShapeIndex { public: void Add(S2Polygon* polygon_disown) { auto polygon = std::unique_ptr(polygon_disown); $self->Add(std::unique_ptr(new S2Polygon::OwningShape(std::move(polygon)))); } } %extend S2BooleanOperation { public: S2BooleanOperation(OpType op_type, S2Builder::Layer* layer_disown) { S2BooleanOperation::Options options; auto layer = std::unique_ptr(layer_disown); return new S2BooleanOperation(op_type, std::move(layer), options); } } class S2BufferOperationOptions { public: S2BufferOperation::Options opts; void set_buffer_radius(S1Angle); void set_error_fraction(double); }; %extend S2BufferOperation { public: S2BufferOperation(S2Builder::Layer* layer_disown) { auto layer = std::unique_ptr(layer_disown); return new S2BufferOperation(std::move(layer)); } S2BufferOperation(S2Builder::Layer* layer_disown, const S2BufferOperationOptions& options) { auto layer = std::unique_ptr(layer_disown); return new S2BufferOperation(std::move(layer), options.opts); } void AddPolygon(S2Polygon* polygon_disown) { auto polygon = std::unique_ptr(polygon_disown); $self->AddShape(S2Polygon::OwningShape(std::move(polygon))); } void AddPoint(S2Point& point) { $self->AddPoint(point); } } // Expose Options functions on S2RegionCoverer until we figure out // nested classes in SWIG. %extend S2RegionCoverer { int max_cells() const { return $self->options().max_cells(); } void set_max_cells(int max_cells) { $self->mutable_options()->set_max_cells(max_cells); } int min_level() const { return $self->options().min_level(); } void set_min_level(int min_level) { $self->mutable_options()->set_min_level(min_level); } int max_level() const { return $self->options().max_level(); } void set_max_level(int max_level) { $self->mutable_options()->set_max_level(max_level); } void set_fixed_level(int fixed_level) { $self->mutable_options()->set_fixed_level(fixed_level); } int level_mod() const { return $self->options().level_mod(); } void set_level_mod(int level_mod) { $self->mutable_options()->set_level_mod(level_mod); } int true_max_level() const { return $self->options().true_max_level(); } } // Expose Options functions on S2RegionTermIndexer until we figure out // nested classes in SWIG. %extend S2RegionTermIndexer { int max_cells() const { return $self->options().max_cells(); } void set_max_cells(int max_cells) { $self->mutable_options()->set_max_cells(max_cells); } int min_level() const { return $self->options().min_level(); } void set_min_level(int min_level) { $self->mutable_options()->set_min_level(min_level); } int max_level() const { return $self->options().max_level(); } void set_max_level(int max_level) { $self->mutable_options()->set_max_level(max_level); } void set_fixed_level(int fixed_level) { $self->mutable_options()->set_fixed_level(fixed_level); } int level_mod() const { return $self->options().level_mod(); } void set_level_mod(int level_mod) { $self->mutable_options()->set_level_mod(level_mod); } int true_max_level() const { return $self->options().true_max_level(); } bool index_contains_points_only() const { return $self->options().index_contains_points_only(); } void set_index_contains_points_only(bool value) { $self->mutable_options()->set_index_contains_points_only(value); } bool optimize_for_space() const { return $self->options().optimize_for_space(); } void set_optimize_for_space(bool value) { $self->mutable_options()->set_optimize_for_space(value); } char marker_character() const { return $self->options().marker_character(); } void set_marker_character(char ch) { $self->mutable_options()->set_marker_character(ch); } } %copyctor S1ChordAngle; // Raise ValueError for any functions that would trigger a // ABSL_CHECK/ABSL_DCHECK. %pythonprepend S2CellId::child %{ if not self.is_valid(): raise ValueError("S2CellId must be valid.") if self.is_leaf(): raise ValueError("S2CellId must be non-leaf.") if not 0 <= position < 4: raise ValueError("Position must be 0-3.") %} // TODO(jrosenstock): child_begin() // TODO(jrosenstock): child_end() %pythonprepend S2CellId::child_position(int) const %{ if not self.is_valid(): raise ValueError("S2CellId must be valid.") if level < 1 or level > self.level(): raise ValueError("level must must be in range [1, S2 cell level]") %} %pythonprepend S2CellId::contains %{ if not self.is_valid() or not other.is_valid(): raise ValueError("Both S2CellIds must be valid.") %} %pythonprepend S2CellId::intersects %{ if not self.is_valid() or not other.is_valid(): raise ValueError("Both S2CellIds must be valid.") %} %pythonprepend S2CellId::level %{ # As in the C++ version: # We can't just check is_valid() because we want level() to be # defined for end-iterators, i.e. S2CellId.End(level). However there is # no good way to define S2CellId::None().level(), so we do prohibit that. if self.id() == 0: raise ValueError("None has no level.") %} %pythonprepend S2CellId::parent %{ if not self.is_valid(): raise ValueError("S2CellId must be valid.") if len(args) == 1: level, = args if level < 0: raise ValueError("Level must be non-negative.") if level > self.level(): raise ValueError("Level must be less than or equal to cell's level.") %} %ignoreall %unignore MutableS2ShapeIndex; %unignore MutableS2ShapeIndex::~MutableS2ShapeIndex; %unignore MutableS2ShapeIndex::Add(S2Shape*); %unignore R1Interval; %ignore R1Interval::operator[]; %unignore R1Interval::GetLength; %unignore S1Angle; %unignore S1Angle::S1Angle; %unignore S1Angle::~S1Angle; %unignore S1Angle::Degrees; %unignore S1Angle::E5; %unignore S1Angle::E6; %unignore S1Angle::E7; %unignore S1Angle::Normalize; %unignore S1Angle::Normalized; %unignore S1Angle::Radians; %unignore S1Angle::UnsignedE6; %unignore S1Angle::abs; %unignore S1Angle::degrees; %unignore S1Angle::e6; %unignore S1Angle::e7; %unignore S1Angle::radians; %unignore S1ChordAngle; %unignore S1ChordAngle::ToAngle; %unignore S1ChordAngle::degrees; %unignore S1ChordAngle::Infinity; %unignore S1Interval; %ignore S1Interval::operator[]; %unignore S1Interval::GetLength; %unignore S2; %unignore S2::CrossingSign; %unignore S2::GetIntersection; %unignore S2::Interpolate; %unignore S2::Rotate; %unignore S2::TurnAngle; %unignore S2::UpdateMinDistance; %unignore S2BooleanOperation; %unignore S2BooleanOperation::Build; %unignore S2BooleanOperation::OpType; %unignore S2BooleanOperation::OpType::UNION; %unignore S2BooleanOperation::OpType::INTERSECTION; %unignore S2BooleanOperation::OpType::DIFFERENCE; %unignore S2BooleanOperation::OpType::SYMMETRIC_DIFFERENCE; %unignore S2BooleanOperation::S2BooleanOperation(OpType, S2Builder::Layer*, const Options&); %ignore S2BooleanOperation::S2BooleanOperation(OpType, std::unique_ptr, const Options&); %ignore S2BooleanOperation::S2BooleanOperation(OpType, std::unique_ptr); // Silence SWIG Warning 362: operator= can't be wrapped in Python. %ignore S2BooleanOperation::operator=; %unignore S2BufferOperation; %unignore S2BufferOperation::Build; %unignore S2BufferOperation::Options; %unignore S2BufferOperation::S2BufferOperation(S2Builder::Layer*); %ignore S2BufferOperation::S2BufferOperation(std::unique_ptr); %ignore S2BufferOperation::S2BufferOperation(std::unique_ptr, const Options&); // Silence SWIG Warning 362: operator= can't be wrapped in Python. %ignore S2BufferOperation::operator=; // Silence SWIG Warning 325: nested class Options can't be wrapped directly. // S2BufferOperationOptions provides a workaround wrapper. %warnfilter(325) S2BufferOperation; %unignore S2BufferOperationOptions; %unignore S2BufferOperationOptions::set_buffer_radius; %unignore S2BufferOperationOptions::set_error_fraction; %unignore S2Builder; %unignore S2Builder::Layer; %unignore S2Builder::S2Builder; %unignore S2Builder::StartLayer(S2Builder::Layer*); %unignore S2Builder::AddEdge; %unignore S2Builder::Build; %unignore S2Builder::EdgeType; %unignore S2Builder::EdgeType::DIRECTED; %unignore S2Builder::EdgeType::UNDIRECTED; %unignore s2builderutil; %unignore s2builderutil::S2PolygonLayer; %unignore s2builderutil::S2PolygonLayer::S2PolygonLayer(S2Polygon*); %unignore S2Cap; %unignore S2Cap::S2Cap; %unignore S2Cap::~S2Cap; %unignore S2Cap::AddPoint; %unignore S2Cap::ApproxEquals; %unignore S2Cap::Clone; %unignore S2Cap::Contains; %unignore S2Cap::Decode; %unignore S2Cap::Empty; %unignore S2Cap::Encode; %unignore S2Cap::Expanded; %unignore S2Cap::FromCenterArea(const S2Point&, double); %unignore S2Cap::FromCenterHeight(const S2Point&, double); %unignore S2Cap::FromPoint; %unignore S2Cap::Full; %unignore S2Cap::GetCapBound() const; %unignore S2Cap::GetCentroid; %unignore S2Cap::GetRectBound; %unignore S2Cap::Intersects; %unignore S2Cap::MayIntersect(const S2Cell&) const; %unignore S2Cap::Union; %unignore S2Cap::center; %unignore S2Cap::height; %unignore S2Cap::is_empty; %unignore S2Cap::is_valid; %unignore S2Cell; %unignore S2Cell::S2Cell; %unignore S2Cell::~S2Cell; %unignore S2Cell::ApproxArea; %unignore S2Cell::AverageArea; %unignore S2Cell::Clone; %unignore S2Cell::Contains; %unignore S2Cell::Decode; %unignore S2Cell::Encode; %unignore S2Cell::ExactArea; %unignore S2Cell::GetBoundaryDistance; %unignore S2Cell::GetCapBound() const; %unignore S2Cell::GetCenter; %unignore S2Cell::GetDistance; %unignore S2Cell::GetRectBound; %unignore S2Cell::GetS2LatLngEdge; %unignore S2Cell::GetS2LatLngVertex; %unignore S2Cell::GetVertex; %unignore S2Cell::MayIntersect(const S2Cell&) const; %unignore S2Cell::face; %unignore S2Cell::id; %unignore S2Cell::level; %unignore S2CellId; %unignore S2CellId::S2CellId; %unignore S2CellId::~S2CellId; %unignore S2CellId::AppendAllNeighbors(int, std::vector*) const; %rename(GetAllNeighbors) S2CellId::AppendAllNeighbors(int, std::vector*) const; %unignore S2CellId::AppendVertexNeighbors(int, std::vector*) const; %rename(GetVertexNeighbors) S2CellId::AppendVertexNeighbors(int, std::vector*) const; %unignore S2CellId::Begin; %unignore S2CellId::End; %unignore S2CellId::FromDebugString(absl::string_view); %unignore S2CellId::FromFaceIJ(int, int, int); %unignore S2CellId::FromFacePosLevel(int, uint64_t, int); %unignore S2CellId::FromLatLng; %unignore S2CellId::FromPoint; %unignore S2CellId::FromToken(absl::string_view); %unignore S2CellId::GetCenterSiTi(int*, int*) const; %unignore S2CellId::GetEdgeNeighbors; %unignore S2CellId::ToFaceIJOrientation(int*, int*, int*) const; %unignore S2CellId::ToLatLng; %unignore S2CellId::ToPoint; %unignore S2CellId::ToString; %unignore S2CellId::ToToken; %unignore S2CellId::child; %unignore S2CellId::child_begin; %unignore S2CellId::child_end; %unignore S2CellId::child_position(int) const; %unignore S2CellId::contains; %unignore S2CellId::face; %unignore S2CellId::id; %unignore S2CellId::intersects; %unignore S2CellId::is_leaf; %unignore S2CellId::is_face; %unignore S2CellId::is_valid; %unignore S2CellId::kMaxLevel; %unignore S2CellId::level; %unignore S2CellId::next; %unignore S2CellId::parent; %unignore S2CellId::pos; %unignore S2CellId::prev; %unignore S2CellId::range_max; %unignore S2CellId::range_min; %unignore S2CellUnion; %ignore S2CellUnion::operator[]; // Silence the SWIG warning. %unignore S2CellUnion::S2CellUnion(const std::vector &); %unignore S2CellUnion::~S2CellUnion; %unignore S2CellUnion::ApproxArea; %unignore S2CellUnion::Clone; %unignore S2CellUnion::Contains; %unignore S2CellUnion::Decode; %unignore S2CellUnion::Denormalize(int, int, std::vector*) const; %unignore S2CellUnion::Encode; %unignore S2CellUnion::ExactArea; %unignore S2CellUnion::FromNormalized(std::vector); %unignore S2CellUnion::GetCapBound() const; %unignore S2CellUnion::GetDifference; %unignore S2CellUnion::GetRectBound; %unignore S2CellUnion::Init(std::vector const &); %unignore S2CellUnion::Intersection; %unignore S2CellUnion::Intersects; %unignore S2CellUnion::IsNormalized() const; %unignore S2CellUnion::MayIntersect(const S2Cell&) const; // SWIG doesn't handle disambiguation of the overloaded Normalize methods, so // the Normalize() instance method is renamed to NormalizeS2CellUnion. %unignore S2CellUnion::Normalize(std::vector*); %unignore S2CellUnion::cell_id; %unignore S2CellUnion::cell_ids; %unignore S2CellUnion::empty; %unignore S2CellUnion::num_cells; %unignore S2Earth; %unignore S2Earth::GetDistance(const S2LatLng&, const S2LatLng&); %unignore S2Earth::GetDistance(const S2Point&, const S2Point&); %unignore S2Earth::GetDistanceKm(const S2LatLng&, const S2LatLng&); %unignore S2Earth::GetDistanceKm(const S2Point&, const S2Point&); %unignore S2Earth::GetDistanceMeters(const S2LatLng&, const S2LatLng&); %unignore S2Earth::GetDistanceMeters(const S2Point&, const S2Point&); %unignore S2Earth::GetInitialBearing(const S2LatLng&, const S2LatLng&); %unignore S2Earth::HighestAltitude(); %unignore S2Earth::HighestAltitudeKm(); %unignore S2Earth::HighestAltitudeMeters(); %unignore S2Earth::KmToRadians(double); %unignore S2Earth::LowestAltitude(); %unignore S2Earth::LowestAltitudeKm(); %unignore S2Earth::LowestAltitudeMeters(); %unignore S2Earth::MetersToRadians(double); %unignore S2Earth::RadiansToKm(double); %unignore S2Earth::RadiansToMeters(double); %unignore S2Earth::Radius(); %unignore S2Earth::RadiusKm(); %unignore S2Earth::RadiusMeters(); %unignore S2Earth::SquareKmToSteradians(double); %unignore S2Earth::SquareMetersToSteradians(double); %unignore S2Earth::SteradiansToSquareKm(double); %unignore S2Earth::SteradiansToSquareMeters(double); %unignore S2Earth::ToAngle(const util::units::Meters&); %unignore S2Earth::ToChordAngle(const util::units::Meters&); %unignore S2Earth::ToDistance(const S1Angle&); %unignore S2Earth::ToDistance(const S1ChordAngle&); %unignore S2Earth::ToKm(const S1Angle&); %unignore S2Earth::ToKm(const S1ChordAngle&); %unignore S2Earth::ToLongitudeRadians(const util::units::Meters&, double); %unignore S2Earth::ToMeters(const S1Angle&); %unignore S2Earth::ToMeters(const S1ChordAngle&); %unignore S2Earth::ToRadians(const util::units::Meters&); %unignore S2LatLng; %unignore S2LatLng::S2LatLng; %unignore S2LatLng::~S2LatLng; %unignore S2LatLng::ApproxEquals; %unignore S2LatLng::FromDegrees; %unignore S2LatLng::FromE6; %unignore S2LatLng::FromE7; %unignore S2LatLng::FromRadians; %unignore S2LatLng::FromUnsignedE6; %unignore S2LatLng::FromUnsignedE7; %unignore S2LatLng::GetDistance; %unignore S2LatLng::Normalized; %unignore S2LatLng::ToPoint; %unignore S2LatLng::ToStringInDegrees; %unignore S2LatLng::coords; %unignore S2LatLng::is_valid; %unignore S2LatLng::lat; %unignore S2LatLng::lng; %unignore S2LatLngRect; %unignore S2LatLngRect::S2LatLngRect; %unignore S2LatLngRect::~S2LatLngRect; %unignore S2LatLngRect::AddPoint; %unignore S2LatLngRect::ApproxEquals; %unignore S2LatLngRect::Area; %unignore S2LatLngRect::Clone; %unignore S2LatLngRect::Contains; %unignore S2LatLngRect::Decode; %unignore S2LatLngRect::Empty; %unignore S2LatLngRect::Encode; %unignore S2LatLngRect::ExpandedByDistance; %unignore S2LatLngRect::FromCenterSize; %unignore S2LatLngRect::FromPoint; %unignore S2LatLngRect::FromPointPair; %unignore S2LatLngRect::Full; %unignore S2LatLngRect::GetCapBound() const; %unignore S2LatLngRect::GetCenter; %unignore S2LatLngRect::GetCentroid; %unignore S2LatLngRect::GetDistance; %unignore S2LatLngRect::GetRectBound; %unignore S2LatLngRect::GetSize; %unignore S2LatLngRect::GetVertex; %unignore S2LatLngRect::Intersection; %unignore S2LatLngRect::Intersects; %unignore S2LatLngRect::MayIntersect(const S2Cell&) const; %unignore S2LatLngRect::Union; %unignore S2LatLngRect::hi; %unignore S2LatLngRect::is_empty; %unignore S2LatLngRect::is_point; %unignore S2LatLngRect::is_valid; %unignore S2LatLngRect::lat; %unignore S2LatLngRect::lat_hi; %unignore S2LatLngRect::lat_lo; %unignore S2LatLngRect::lng; %unignore S2LatLngRect::lng_hi; %unignore S2LatLngRect::lng_lo; %unignore S2LatLngRect::lo; %unignore S2Loop; %unignore S2Loop::~S2Loop; %unignore S2Loop::Clone; %unignore S2Loop::Contains; %unignore S2Loop::Decode; %unignore S2Loop::Encode; %unignore S2Loop::Equals; %unignore S2Loop::GetArea; %unignore S2Loop::GetCapBound() const; %unignore S2Loop::GetCentroid; %unignore S2Loop::GetDistance; %unignore S2Loop::GetRectBound; %unignore S2Loop::GetS2LatLngVertex; %unignore S2Loop::Intersects; %unignore S2Loop::IsNormalized() const; %unignore S2Loop::IsValid; %unignore S2Loop::MayIntersect(const S2Cell&) const; %unignore S2Loop::Normalize; %unignore S2Loop::Project; %unignore S2Loop::depth; %unignore S2Loop::is_empty; %unignore S2Loop::is_hole; %unignore S2Loop::num_vertices; %unignore S2Loop::sign; %unignore S2Loop::vertex; %unignore S2Polygon; %unignore S2Polygon::S2Polygon; %ignore S2Polygon::S2Polygon(std::unique_ptr, S2Debug); %ignore S2Polygon::S2Polygon(std::unique_ptr); %ignore S2Polygon::S2Polygon(std::vector>, S2Debug); %ignore S2Polygon::S2Polygon(std::vector>); %unignore S2Polygon::~S2Polygon; %unignore S2Polygon::BoundaryNear; %unignore S2Polygon::Clone; %unignore S2Polygon::Contains; %unignore S2Polygon::Copy; %unignore S2Polygon::Decode; %unignore S2Polygon::Encode; %unignore S2Polygon::Equals; %unignore S2Polygon::GetArea; %unignore S2Polygon::GetCapBound() const; %unignore S2Polygon::GetCentroid; %unignore S2Polygon::GetDistance; %unignore S2Polygon::GetLastDescendant(int) const; %unignore S2Polygon::GetOverlapFractions(const S2Polygon&, const S2Polygon&); %unignore S2Polygon::GetRectBound; %unignore S2Polygon::Init; %ignore S2Polygon::Init(std::unique_ptr); %unignore S2Polygon::InitNested; %ignore S2Polygon::InitNested(std::vector>); %unignore S2Polygon::InitToUnion; %unignore S2Polygon::Intersects; %unignore S2Polygon::IsValid; %unignore S2Polygon::MayIntersect(const S2Cell&) const; %unignore S2Polygon::Project; %unignore S2Polygon::is_empty; %unignore S2Polygon::loop; %unignore S2Polygon::num_loops; %unignore S2Polygon::num_vertices; %unignore S2Polyline; %unignore S2Polyline::S2Polyline(); %unignore S2Polyline::S2Polyline(std::vector const &); %ignore S2Polyline::S2Polyline(std::vector const &); %ignore S2Polyline::S2Polyline(std::vector const &, S2Debug); %unignore S2Polyline::~S2Polyline; %unignore S2Polyline::ApproxEquals; %unignore S2Polyline::Clone; %unignore S2Polyline::Contains; %unignore S2Polyline::Decode; %unignore S2Polyline::Encode; %unignore S2Polyline::GetCapBound() const; %unignore S2Polyline::GetCentroid; %unignore S2Polyline::GetLength; %unignore S2Polyline::GetRectBound; %unignore S2Polyline::GetSuffix; %unignore S2Polyline::Interpolate; %unignore S2Polyline::Intersects; %unignore S2Polyline::IsOnRight; %unignore S2Polyline::IsValid; %unignore S2Polyline::MayIntersect(const S2Cell&) const; %unignore S2Polyline::Project; %unignore S2Polyline::Reverse; %unignore S2Polyline::UnInterpolate; %unignore S2Polyline::num_vertices; %unignore S2Polyline::vertex; %unignore s2pred; %unignore s2pred::OrderedCCW; %unignore S2RegionCoverer; %unignore S2RegionCoverer::S2RegionCoverer; %unignore S2RegionCoverer::~S2RegionCoverer; %unignore S2RegionCoverer::GetCovering(const S2Region&, std::vector*); %unignore S2RegionCoverer::GetInteriorCovering(const S2Region&, std::vector*); %unignore S2RegionTermIndexer; %unignore S2RegionTermIndexer::S2RegionTermIndexer; %unignore S2RegionTermIndexer::~S2RegionTermIndexer; %unignore S2RegionTermIndexer::GetIndexTerms(const S2Point&, absl::string_view); %unignore S2RegionTermIndexer::GetIndexTerms(const S2Region&, absl::string_view); %unignore S2RegionTermIndexer::GetIndexTermsForCanonicalCovering( const S2CellUnion&, absl::string_view); %unignore S2RegionTermIndexer::GetQueryTerms(const S2Point&, absl::string_view); %unignore S2RegionTermIndexer::GetQueryTerms(const S2Region&, absl::string_view); %unignore S2RegionTermIndexer::GetQueryTermsForCanonicalCovering( const S2CellUnion&, absl::string_view); %unignore S2ShapeIndex; %include "s2/r1interval.h" %include "s2/s1angle.h" %include "s2/s1chord_angle.h" %include "s2/s1interval.h" %include "s2/s2boolean_operation.h" %include "s2/s2buffer_operation.h" %include "s2/s2builder.h" %include "s2/s2builder_layer.h" %include "s2/s2builderutil_s2polygon_layer.h" %include "s2/s2cell_id.h" %include "s2/s2edge_crossings.h" %include "s2/s2edge_distances.h" %include "s2/s2earth.h" %include "s2/s2region.h" %include "s2/s2cap.h" %include "s2/s2latlng.h" %include "s2/s2latlng_rect.h" %include "s2/s2loop.h" %include "s2/s2measures.h" %include "s2/s2pointutil.h" %include "s2/s2polygon.h" %include "s2/s2polyline.h" %include "s2/s2predicates.h" %include "s2/s2region_coverer.h" %include "s2/s2region_term_indexer.h" %include "s2/s2cell.h" %include "s2/s2cell_union.h" %include "s2/s2shape_index.h" %include "s2/mutable_s2shape_index.h" %unignoreall %define USE_STREAM_INSERTOR_FOR_STR(type) %extend type { std::string __str__() { std::ostringstream output; output << *$self; return output.str(); } } %enddef %define USE_EQUALS_FN_FOR_EQ_AND_NE(type) %extend type { bool __eq__(const type& other) { return $self->Equals(other); } bool __ne__(const type& other) { return !$self->Equals(other); } } %enddef %define USE_EQUALS_FOR_EQ_AND_NE(type) %extend type { bool __eq__(const type& other) { return *$self == other; } bool __ne__(const type& other) { return *$self != other; } } %enddef %define USE_COMPARISON_FOR_LT_AND_GT(type) %extend type { bool __lt__(const type& other) { return *$self < other; } bool __gt__(const type& other) { return *$self > other; } } %enddef %define USE_ARITHMETIC_FOR_ADD_AND_SUB(type) %extend type { type __add__(const type& other) { return *$self + other; } type __sub__(const type& other) { return *$self - other; } } %enddef %define USE_HASH_FOR_TYPE(type, hash_type) %extend type { size_t __hash__() { return hash_type()(*$self); } } %enddef USE_STREAM_INSERTOR_FOR_STR(S1Angle) USE_STREAM_INSERTOR_FOR_STR(S1Interval) USE_STREAM_INSERTOR_FOR_STR(S2CellId) USE_STREAM_INSERTOR_FOR_STR(S2Cap) USE_STREAM_INSERTOR_FOR_STR(S2LatLng) USE_STREAM_INSERTOR_FOR_STR(S2LatLngRect) USE_EQUALS_FOR_EQ_AND_NE(S2CellId) USE_COMPARISON_FOR_LT_AND_GT(S2CellId) USE_HASH_FOR_TYPE(S2CellId, S2CellIdHash) USE_EQUALS_FOR_EQ_AND_NE(S1Angle) USE_COMPARISON_FOR_LT_AND_GT(S1Angle) USE_EQUALS_FOR_EQ_AND_NE(S1ChordAngle) USE_COMPARISON_FOR_LT_AND_GT(S1ChordAngle) USE_ARITHMETIC_FOR_ADD_AND_SUB(S1ChordAngle) USE_EQUALS_FN_FOR_EQ_AND_NE(S2Loop) USE_EQUALS_FN_FOR_EQ_AND_NE(S2Polygon) USE_EQUALS_FN_FOR_EQ_AND_NE(S2Polyline) // Simple implementation of key S2Testing methods %pythoncode %{ import random class S2Testing(object): """ Simple implementation of key S2Testing methods. """ _rnd = random.Random(1) @classmethod def RandomPoint(cls): """ Return a random unit-length vector. """ x = cls._rnd.uniform(-1, 1) y = cls._rnd.uniform(-1, 1) z = cls._rnd.uniform(-1, 1) return S2Point_FromRaw(x, y, z).Normalize() @classmethod def GetRandomCap(cls, min_area, max_area): """ Return a cap with a random axis such that the log of its area is uniformly distributed between the logs of the two given values. (The log of the cap angle is also approximately uniformly distributed.) """ cap_area = max_area * pow(min_area / max_area, cls._rnd.random()) assert cap_area >= min_area assert cap_area <= max_area # The surface area of a cap is 2*Pi times its height. return S2Cap.FromCenterArea(cls.RandomPoint(), cap_area) %} src/python/s2cap_bindings.cc000066400000000000000000000211101524103652300163560ustar00rootroot00000000000000#include #include #include #include #include #include "absl/hash/hash.h" #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2cap.h" #include "s2/s2cell.h" #include "s2/s2cell_id.h" #include "s2/s2point.h" namespace py = pybind11; void bind_s2cap(py::module& m) { py::class_(m, "S2Cap", "A disc-shaped region defined by a center and radius on the sphere.\n\n" "The cap represents a portion of the unit sphere cut off by a plane.\n" "The boundary is a circle; the cap is a closed set (contains its\n" "boundary). A cap of radius Pi/2 is a hemisphere; Pi covers the full\n" "sphere. See s2/s2cap.h for comprehensive documentation.") // Constructors .def(py::init<>(), "Construct an empty S2Cap.") .def(py::init([](const S2Point& center, S1Angle radius) { return S2Cap(center.Normalize(), radius); }), py::arg("center"), py::arg("radius"), "Construct a cap with the given center and radius.\n\n" "center is normalized if not already unit length. Negative radius\n" "produces the empty cap; radius >= 180 degrees produces the full cap.") .def(py::init([](const S2Point& center, S1ChordAngle radius) { return S2Cap(center.Normalize(), radius); }), py::arg("center"), py::arg("radius"), "Construct a cap with the given center and radius as S1ChordAngle.\n\n" "center is normalized if not already unit length.") // Factory methods .def_static("from_point", [](const S2Point& center) { return S2Cap::FromPoint(center.Normalize()); }, py::arg("center"), "Return a cap containing a single point.\n\n" "center is normalized if not already unit length.") .def_static("from_center_height", [](const S2Point& center, double height) { return S2Cap::FromCenterHeight(center.Normalize(), height); }, py::arg("center"), py::arg("height"), "Return a cap with the given center and height.\n\n" "Height is the distance from the center point to the cutoff plane.\n" "center is normalized if not already unit length.\n" "A negative height yields an empty cap; height >= 2 yields a full cap.") .def_static("from_center_area", [](const S2Point& center, double area) { return S2Cap::FromCenterArea(center.Normalize(), area); }, py::arg("center"), py::arg("area"), "Return a cap with the given center and surface area in steradians.\n\n" "The area also equals the solid angle subtended by the cap.\n" "center is normalized if not already unit length.\n" "A negative area yields an empty cap; area >= 4*Pi yields a full cap.") .def_static("empty", &S2Cap::Empty, "Return an empty cap (contains no points).") .def_static("full", &S2Cap::Full, "Return a full cap (contains all points).") .def_static("from_points", [](const std::vector& points) { if (points.empty()) return S2Cap::Empty(); S2Cap result = S2Cap::FromPoint(points[0].Normalize()); for (size_t i = 1; i < points.size(); ++i) result.AddPoint(points[i].Normalize()); return result; }, py::arg("points"), "Return the smallest cap containing all given points.\n\n" "Returns the empty cap if the list is empty.") .def_static("from_caps", [](const std::vector& caps) { if (caps.empty()) return S2Cap::Empty(); S2Cap result = caps[0]; for (size_t i = 1; i < caps.size(); ++i) result.AddCap(caps[i]); return result; }, py::arg("caps"), "Return the smallest cap containing all given caps.\n\n" "Returns the empty cap if the list is empty.") // Properties .def_property_readonly("center", &S2Cap::center, "The center of the cap as a unit-length S2Point.") .def_property_readonly("radius", &S2Cap::radius, "The radius as an S1ChordAngle.") .def_property_readonly("height", &S2Cap::height, "The height of the cap (distance from center point to cutoff plane).") // Geometric operations .def("radius_angle", &S2Cap::GetRadius, "Return the radius as an S1Angle.\n\n" "Requires a trigonometric operation; may differ slightly from the\n" "value passed to the S1Angle constructor.") .def("area", &S2Cap::GetArea, "Return the surface area of the cap in steradians.") .def("centroid", &S2Cap::GetCentroid, "Return the true centroid of the cap multiplied by its surface area.\n\n" "The result lies on the ray from the origin through the cap's center.\n" "For zero-radius caps, always returns the origin (0, 0, 0).") // Predicates .def("is_empty", &S2Cap::is_empty, "Return true if the cap contains no points.") .def("is_full", &S2Cap::is_full, "Return true if the cap contains all points.") .def("complement", &S2Cap::Complement, "Return the complement of the interior of the cap.\n\n" "Same boundary as this cap but no shared interior points.\n" "Note: complement of a singleton equals complement of an empty cap.") .def("expanded", &S2Cap::Expanded, py::arg("distance"), "Return a cap containing all points within distance of this cap.\n\n" "Any expansion of an empty cap is still empty.") .def("union", &S2Cap::Union, py::arg("other"), "Return the smallest cap enclosing this cap and other.") // Containment / intersection .def("contains", py::overload_cast( &S2Cap::Contains, py::const_), py::arg("other"), "Return true if this cap contains the given cap.") .def("contains_point", py::overload_cast( &S2Cap::Contains, py::const_), py::arg("point"), "Return true if this cap contains the given point.\n\n" "point should be unit length.") .def("contains_cell", py::overload_cast( &S2Cap::Contains, py::const_), py::arg("cell"), "Return true if this cap contains the given cell.") .def("intersects", py::overload_cast( &S2Cap::Intersects, py::const_), py::arg("other"), "Return true if this cap intersects the given cap.") .def("interior_intersects", &S2Cap::InteriorIntersects, py::arg("other"), "Return true if the interior of this cap intersects other.\n\n" "This relationship is not symmetric: only the interior of this cap\n" "is tested, not the interior of other.") .def("interior_contains_point", &S2Cap::InteriorContains, py::arg("point"), "Return true if the interior of this cap contains the given point.\n\n" "point should be unit length.") .def("may_intersect", &S2Cap::MayIntersect, py::arg("cell"), "Return true if this cap may intersect the given cell.") .def("cap_bound", &S2Cap::GetCapBound, "Return a bounding cap for this cap (returns self).") // get_rect_bound() is deferred until S2LatLngRect is bound. .def("cell_union_bound", [](const S2Cap& self) { std::vector cell_ids; self.GetCellUnionBound(&cell_ids); return cell_ids; }, "Return a list of S2CellIds whose union covers this cap.") // Operators .def(py::self == py::self, "Return true if caps are identical.") .def(py::self != py::self, "Return true if caps are not identical.") .def("approx_equals", &S2Cap::ApproxEquals, py::arg("other"), py::arg("max_error") = S1Angle::Radians(1e-14), "Return true if this cap is approximately equal to other.\n\n" "Checks that the angle between centers and the difference in chord\n" "radii are both within max_error radians.") .def("__hash__", [](const S2Cap& self) { return absl::HashOf(self); }) // String representation .def("__repr__", [](const S2Cap& self) { std::ostringstream oss; oss << "S2Cap(" << self << ")"; return oss.str(); }) .def("__str__", [](const S2Cap& self) { std::ostringstream oss; oss << self; return oss.str(); }); } src/python/s2cap_test.py000066400000000000000000000252441524103652300156170ustar00rootroot00000000000000"""Tests for S2Cap pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS2Cap(unittest.TestCase): """Test cases for S2Cap bindings.""" # Constructors def test_default_constructor_is_empty(self): cap = s2.S2Cap() self.assertTrue(cap.is_empty()) self.assertFalse(cap.is_full()) def test_constructor_s1angle(self): center = s2.S2Point(1.0, 0.0, 0.0) radius = s2.S1Angle.from_radians(math.pi / 4) cap = s2.S2Cap(center, radius) self.assertFalse(cap.is_empty()) self.assertFalse(cap.is_full()) def test_constructor_s1chord_angle(self): center = s2.S2Point(1.0, 0.0, 0.0) radius = s2.S1ChordAngle(s2.S1Angle.from_radians(math.pi / 4)) cap = s2.S2Cap(center, radius) self.assertFalse(cap.is_empty()) def test_constructor_negative_radius_is_empty(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(-1.0)) self.assertTrue(cap.is_empty()) def test_constructor_pi_radius_is_full(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(math.pi)) self.assertTrue(cap.is_full()) def test_constructor_normalizes_center(self): p = s2.S2Point(2.0, 0.0, 0.0) # not unit length cap = s2.S2Cap(p, s2.S1Angle.from_degrees(10.0)) self.assertAlmostEqual(cap.center.norm(), 1.0, places=15) # Factory methods def test_from_point(self): p = s2.S2Point(0.0, 1.0, 0.0) cap = s2.S2Cap.from_point(p) self.assertTrue(cap.contains_point(p)) def test_from_center_height(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap.from_center_height(center, 0.5) self.assertAlmostEqual(cap.height, 0.5) def test_from_center_height_negative_is_empty(self): center = s2.S2Point(1.0, 0.0, 0.0) self.assertTrue(s2.S2Cap.from_center_height(center, -1.0).is_empty()) def test_from_center_height_two_is_full(self): center = s2.S2Point(1.0, 0.0, 0.0) self.assertTrue(s2.S2Cap.from_center_height(center, 2.0).is_full()) def test_from_center_area(self): center = s2.S2Point(1.0, 0.0, 0.0) area = 2 * math.pi # hemisphere cap = s2.S2Cap.from_center_area(center, area) self.assertAlmostEqual(cap.area(), area, places=10) def test_empty(self): cap = s2.S2Cap.empty() self.assertTrue(cap.is_empty()) self.assertFalse(cap.is_full()) def test_full(self): cap = s2.S2Cap.full() self.assertTrue(cap.is_full()) self.assertFalse(cap.is_empty()) def test_from_points_empty(self): cap = s2.S2Cap.from_points([]) self.assertTrue(cap.is_empty()) def test_from_points_single(self): p = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap.from_points([p]) self.assertTrue(cap.contains_point(p)) def test_from_points_multiple(self): p1 = s2.S2Point(1.0, 0.0, 0.0) p2 = s2.S2Point(0.0, 1.0, 0.0) p3 = s2.S2Point(0.0, 0.0, 1.0) cap = s2.S2Cap.from_points([p1, p2, p3]) self.assertTrue(cap.contains_point(p1)) self.assertTrue(cap.contains_point(p2)) self.assertTrue(cap.contains_point(p3)) def test_from_caps_empty(self): cap = s2.S2Cap.from_caps([]) self.assertTrue(cap.is_empty()) def test_from_caps_single(self): c = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_degrees(10.0)) result = s2.S2Cap.from_caps([c]) self.assertTrue(result.contains_point(c.center)) def test_from_caps_multiple(self): c1 = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_degrees(10.0)) c2 = s2.S2Cap(s2.S2Point(0.0, 1.0, 0.0), s2.S1Angle.from_degrees(10.0)) result = s2.S2Cap.from_caps([c1, c2]) self.assertTrue(result.contains_point(c1.center)) self.assertTrue(result.contains_point(c2.center)) # Properties def test_center(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap.from_point(center) self.assertEqual(cap.center, center) def test_radius(self): center = s2.S2Point(1.0, 0.0, 0.0) chord = s2.S1ChordAngle(s2.S1Angle.from_radians(1.0)) cap = s2.S2Cap(center, chord) self.assertEqual(cap.radius, chord) def test_height(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap.from_center_height(center, 0.5) self.assertAlmostEqual(cap.height, 0.5) # Predicates def test_is_empty(self): self.assertTrue(s2.S2Cap.empty().is_empty()) self.assertFalse(s2.S2Cap.full().is_empty()) def test_is_full(self): self.assertTrue(s2.S2Cap.full().is_full()) self.assertFalse(s2.S2Cap.empty().is_full()) # Geometric operations def test_radius_angle(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) self.assertAlmostEqual(cap.radius_angle().radians, 1.0, places=14) def test_area(self): self.assertAlmostEqual(s2.S2Cap.full().area(), 4 * math.pi) self.assertAlmostEqual(s2.S2Cap.empty().area(), 0.0) def test_centroid(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap.from_center_height(center, 0.5) centroid = cap.centroid() # Centroid lies along the same axis as center. self.assertGreater(centroid.x, 0.0) self.assertAlmostEqual(centroid.y, 0.0) self.assertAlmostEqual(centroid.z, 0.0) def test_complement_of_empty_is_full(self): self.assertTrue(s2.S2Cap.empty().complement().is_full()) def test_complement_of_full_is_empty(self): self.assertTrue(s2.S2Cap.full().complement().is_empty()) def test_complement_roundtrip(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) comp = cap.complement() self.assertFalse(comp.is_empty()) self.assertFalse(comp.is_full()) def test_expanded(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap.from_point(center) delta = s2.S1Angle.from_radians(0.1) expanded = cap.expanded(delta) self.assertGreater(expanded.radius_angle().radians, cap.radius_angle().radians) def test_expanded_empty_stays_empty(self): self.assertTrue( s2.S2Cap.empty().expanded(s2.S1Angle.from_radians(1.0)).is_empty()) def test_union_contains_both_centers(self): p1 = s2.S2Point(1.0, 0.0, 0.0) p2 = s2.S2Point(math.cos(0.1), math.sin(0.1), 0.0) cap1 = s2.S2Cap(p1, s2.S1Angle.from_radians(0.01)) cap2 = s2.S2Cap(p2, s2.S1Angle.from_radians(0.01)) u = cap1.union(cap2) # Centers lie strictly inside the union radius, so contains_point is reliable. self.assertTrue(u.contains_point(p1)) self.assertTrue(u.contains_point(p2)) def test_full_contains_any_cap(self): cap = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertTrue(s2.S2Cap.full().contains(cap)) def test_empty_contained_by_any_cap(self): cap = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.contains(s2.S2Cap.empty())) def test_contains_point(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.contains_point(center)) self.assertFalse(cap.contains_point(s2.S2Point(-1.0, 0.0, 0.0))) def test_contains_cell(self): cell = s2.S2Cell(s2.S2CellId(s2.S2Point(1.0, 0.0, 0.0))) self.assertTrue(s2.S2Cap.full().contains_cell(cell)) self.assertFalse(s2.S2Cap.empty().contains_cell(cell)) def test_intersects(self): cap = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.intersects(cap)) self.assertFalse(cap.intersects(s2.S2Cap.empty())) def test_interior_intersects(self): cap = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.interior_intersects(cap)) def test_interior_contains_point(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.interior_contains_point(center)) def test_may_intersect(self): cell = s2.S2Cell(s2.S2CellId(s2.S2Point(1.0, 0.0, 0.0))) self.assertTrue(s2.S2Cap.full().may_intersect(cell)) def test_cap_bound(self): center = s2.S2Point(1.0, 0.0, 0.0) cap = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) bound = cap.cap_bound() self.assertTrue(bound.approx_equals(cap)) def test_cell_union_bound(self): cell_ids = s2.S2Cap.full().cell_union_bound() self.assertGreater(len(cell_ids), 0) # Operators def test_equality(self): center = s2.S2Point(1.0, 0.0, 0.0) cap1 = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) cap2 = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) self.assertTrue(cap1 == cap2) self.assertFalse(cap1 != cap2) def test_inequality(self): cap1 = s2.S2Cap.from_point(s2.S2Point(1.0, 0.0, 0.0)) cap2 = s2.S2Cap.from_point(s2.S2Point(0.0, 1.0, 0.0)) self.assertTrue(cap1 != cap2) self.assertFalse(cap1 == cap2) def test_approx_equals(self): cap = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.approx_equals(cap)) def test_approx_equals_with_max_error(self): cap = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertTrue(cap.approx_equals(cap, s2.S1Angle.from_radians(1e-10))) def test_approx_equals_false(self): cap1 = s2.S2Cap(s2.S2Point(1.0, 0.0, 0.0), s2.S1Angle.from_radians(1.0)) cap2 = s2.S2Cap(s2.S2Point(0.0, 1.0, 0.0), s2.S1Angle.from_radians(1.0)) self.assertFalse(cap1.approx_equals(cap2)) def test_hash(self): center = s2.S2Point(1.0, 0.0, 0.0) cap1 = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) cap2 = s2.S2Cap(center, s2.S1Angle.from_radians(1.0)) self.assertEqual(hash(cap1), hash(cap2)) s = {cap1, cap2} self.assertEqual(len(s), 1) # String representation def test_repr(self): cap = s2.S2Cap.empty() r = repr(cap) self.assertTrue(r.startswith("S2Cap(")) self.assertIn("Center=", r) self.assertIn("Radius=", r) def test_str(self): cap = s2.S2Cap.empty() s = str(cap) self.assertIn("Center=", s) self.assertIn("Radius=", s) if __name__ == "__main__": unittest.main() src/python/s2cell_bindings.cc000066400000000000000000000263331524103652300165460ustar00rootroot00000000000000#include #include #include #include #include #include #include "absl/hash/hash.h" #include "absl/strings/str_cat.h" #include "s2/s1chord_angle.h" #include "s2/s2cell.h" #include "s2/s2cell_id.h" #include "s2/s2latlng.h" #include "s2/s2point.h" namespace py = pybind11; namespace { // These three helpers are duplicated from s2cell_id_bindings.cc. void MaybeThrowFaceOutOfRange(int face) { if (face < 0 || face >= S2CellId::kNumFaces) { throw py::value_error( absl::StrCat("Face ", face, " out of range [0, ", S2CellId::kNumFaces - 1, "]")); } } void MaybeThrowLevelOutOfRange(int level, int min, int max) { if (level < min || level > max) { throw py::value_error( absl::StrCat("Level ", level, " out of range [", min, ", ", max, "]")); } } void MaybeThrowPositionOutOfRange(uint64_t pos) { if (pos > S2CellId::kMaxPosition) { throw py::value_error( absl::StrCat("pos ", pos, " out of range [0, ", S2CellId::kMaxPosition, "]")); } } } // namespace void bind_s2cell(py::module& m) { auto cls = py::class_(m, "S2Cell", "An S2Region representing a single cell on the sphere.\n\n" "Unlike S2CellId (which is just a 64-bit identifier), S2Cell carries\n" "precomputed state that allows efficient containment and intersection\n" "tests. See s2/s2cell.h for comprehensive documentation.") // Constructors .def(py::init([](S2CellId id) { // No validity check needed: all S2CellId objects reachable from // Python are guaranteed valid by the S2CellId bindings. return S2Cell(id); }), py::arg("cell_id"), "Construct the cell corresponding to the given S2CellId.") .def(py::init([](const S2Point& p) { return S2Cell(p); }), py::arg("point"), "Construct a leaf cell containing the given point.\n\n" "The point does not need to be normalized.") .def(py::init([](const S2LatLng& ll) { // No validity check needed: all S2LatLng objects reachable from // Python are guaranteed valid by the S2LatLng bindings. return S2Cell(ll); }), py::arg("latlng"), "Construct a leaf cell containing the given S2LatLng.") // Factory methods .def_static("from_face", [](int face) { MaybeThrowFaceOutOfRange(face); return S2Cell::FromFace(face); }, py::arg("face"), "Return the cell corresponding to the given S2 cube face (0..5).\n\n" "Raises ValueError if face is out of range.") .def_static("from_face_pos_level", [](int face, uint64_t pos, int level) { MaybeThrowFaceOutOfRange(face); MaybeThrowPositionOutOfRange(pos); MaybeThrowLevelOutOfRange(level, 0, S2CellId::kMaxLevel); return S2Cell::FromFacePosLevel(face, pos, level); }, py::arg("face"), py::arg("pos"), py::arg("level"), "Return a cell given its face, Hilbert curve position, and level.\n\n" "Raises ValueError if face, pos, or level is out of range.") // Properties .def_property_readonly("id", &S2Cell::id, "The S2CellId this cell corresponds to") .def_property_readonly("face", &S2Cell::face, "Which cube face this cell belongs to (0..5)") .def_property_readonly("level", &S2Cell::level, "The subdivision level (0..kMaxLevel)") .def_property_readonly("orientation", &S2Cell::orientation, "The Hilbert curve orientation of this cell.\n\n" "A bitmask: bit 0 (kSwapMask) indicates swapped\n" "axes; bit 1 (kInvertMask) indicates 180-degree\n" "rotation. Values are in [0, 3].") // Predicates .def("is_leaf", &S2Cell::is_leaf, "Return true if this is a leaf cell (level == kMaxLevel)") // Geometric operations .def("size_ij", &S2Cell::GetSizeIJ, "Return the edge length of this cell in (i,j)-space") .def("size_st", &S2Cell::GetSizeST, "Return the edge length of this cell in (s,t)-space") .def("vertex", &S2Cell::GetVertex, py::arg("k"), "Return the k-th vertex of the cell (k = 0,1,2,3) in CCW order.\n\n" "Lower-left, lower-right, upper-right, upper-left in the UV plane.\n" "The argument is reduced modulo 4 to the range [0..3].\n" "The returned point is normalized.") .def("edge", &S2Cell::GetEdge, py::arg("k"), "Return the normalized inward-facing normal of the great circle\n" "passing through the edge from vertex k to vertex k+1 (mod 4).\n\n" "The argument is reduced modulo 4 to the range [0..3].") .def("uv_coord_of_edge", &S2Cell::GetUVCoordOfEdge, py::arg("k"), "Return either U or V for the given edge, whichever is constant\n" "along it.\n\n" "Boundaries 0 and 2 return V; boundaries 1 and 3 return U.\n" "The argument is reduced modulo 4 to the range [0..3].") .def("ij_coord_of_edge", &S2Cell::GetIJCoordOfEdge, py::arg("k"), "Return either I or J for the given edge, whichever is constant\n" "along it.\n\n" "Boundaries 0 and 2 return J; boundaries 1 and 3 return I.\n" "The argument is reduced modulo 4 to the range [0..3].") .def("center", &S2Cell::GetCenter, "Return the center of the cell as a normalized S2Point") .def_static("average_area_for_level", [](int level) { MaybeThrowLevelOutOfRange(level, 0, S2CellId::kMaxLevel); return S2Cell::AverageArea(level); }, py::arg("level"), "Return the average area of cells at the given level,\n" "in steradians.\n\n" "Raises ValueError if level is out of range.") .def("approx_area", &S2Cell::ApproxArea, "Return the approximate area of this cell in steradians.\n\n" "Accurate to within 3% for all cell sizes and within 0.1% for\n" "cells at level 5 or higher.") .def("exact_area", &S2Cell::ExactArea, "Return the area of this cell as accurately as possible,\n" "in steradians.\n\n" "More expensive than approx_area but accurate to 6 digits\n" "even for leaf cells.") .def("bound_uv", &S2Cell::GetBoundUV, "Return the bounds of this cell in (u,v)-space") .def("distance", py::overload_cast( &S2Cell::GetDistance, py::const_), py::arg("point"), "Return the distance from this cell to the given point.\n\n" "Returns zero if the point is inside the cell.") .def("boundary_distance", &S2Cell::GetBoundaryDistance, py::arg("point"), "Return the distance from the cell boundary to the given point.") .def("max_distance", py::overload_cast( &S2Cell::GetMaxDistance, py::const_), py::arg("point"), "Return the maximum distance from this cell to the given point.") .def("distance_to_edge", py::overload_cast( &S2Cell::GetDistance, py::const_), py::arg("a"), py::arg("b"), "Return the minimum distance from this cell to the edge AB.\n\n" "Returns zero if the edge intersects the cell interior.") .def("max_distance_to_edge", py::overload_cast( &S2Cell::GetMaxDistance, py::const_), py::arg("a"), py::arg("b"), "Return the maximum distance from this cell to the edge AB.") .def("distance_to_cell", py::overload_cast(&S2Cell::GetDistance, py::const_), py::arg("cell"), "Return the distance from this cell to the given cell.\n\n" "Returns zero if one cell contains the other.") .def("max_distance_to_cell", py::overload_cast(&S2Cell::GetMaxDistance, py::const_), py::arg("cell"), "Return the maximum distance from this cell to the given cell.") .def("cell_union_bound", [](const S2Cell& self) { std::vector cell_ids; self.GetCellUnionBound(&cell_ids); return cell_ids; }, "Return a list of S2CellIds whose union covers this cell.\n\n" "For a single S2Cell, this always returns a list containing\n" "just this cell's id.") .def("contains", py::overload_cast( &S2Cell::Contains, py::const_), py::arg("cell"), "Return true if this cell contains the given cell") .def("contains_point", py::overload_cast( &S2Cell::Contains, py::const_), py::arg("point"), "Return true if this cell contains the given point.\n\n" "S2Cells are closed sets: points along an edge or vertex\n" "belong to the adjacent cell(s) as well.\n" "The point does not need to be normalized.") .def("may_intersect", &S2Cell::MayIntersect, py::arg("cell"), "Return true if this cell may intersect the given cell") .def("subdivide", [](const S2Cell& self) { if (self.is_leaf()) { throw py::value_error("Leaf cell has no children"); } S2Cell children[4]; self.Subdivide(children); return py::make_tuple(children[0], children[1], children[2], children[3]); }, "Return the four children of this cell as a tuple.\n\n" "Raises ValueError if this is a leaf cell.") // Operators .def(py::self == py::self, "Return true if cells are equal") .def(py::self != py::self, "Return true if cells are not equal") .def(py::self < py::self, "Compare cells by their cell id") .def(py::self > py::self, "Compare cells by their cell id") .def(py::self <= py::self, "Compare cells by their cell id") .def(py::self >= py::self, "Compare cells by their cell id") .def("__hash__", [](const S2Cell& self) { return absl::HashOf(self.id()); }) // String representation .def("__repr__", [](const S2Cell& cell) { std::ostringstream oss; oss << "S2Cell(" << cell.id() << ")"; return oss.str(); }) .def("__str__", [](const S2Cell& cell) { std::ostringstream oss; oss << cell.id(); return oss.str(); }); py::enum_(cls, "Boundary", py::arithmetic()) .value("BOTTOM_EDGE", S2Cell::kBottomEdge) .value("RIGHT_EDGE", S2Cell::kRightEdge) .value("TOP_EDGE", S2Cell::kTopEdge) .value("LEFT_EDGE", S2Cell::kLeftEdge) .export_values(); // TODO: The following S2Cell methods are not yet bound because they depend // on types that have not been bound yet: // - get_cap_bound() -> S2Cap // - get_rect_bound() -> S2LatLngRect } src/python/s2cell_id_bindings.cc000066400000000000000000000443341524103652300172230ustar00rootroot00000000000000#include #include #include #include #include #include #include #include #include "absl/strings/str_cat.h" #include "s2/s2cell_id.h" #include "python/s2cell_id_range.h" #include "s2/s2latlng.h" namespace py = pybind11; namespace { void MaybeThrowNotValid(S2CellId id) { if (!id.is_valid()) { throw py::value_error(absl::StrCat("Invalid S2CellId: ", id.ToString())); } } void MaybeThrowLevelOutOfRange(int level, int min, int max) { if (level < min || level > max) { throw py::value_error( absl::StrCat("Level ", level, " out of range [", min, ", ", max, "]")); } } void MaybeThrowFaceOutOfRange(int face) { if (face < 0 || face >= S2CellId::kNumFaces) { throw py::value_error( absl::StrCat("Face ", face, " out of range [0, ", S2CellId::kNumFaces - 1, "]")); } } void MaybeThrowIfLeaf(S2CellId id) { if (id.is_leaf()) { throw py::value_error("Function invalid for leaf cells"); } } void MaybeThrowIfFace(S2CellId id) { if (id.is_face()) { throw py::value_error("Function invalid for face cells"); } } void MaybeThrowCellIdOutOfRange(const char* name, int value, int min, int max) { if (value < min || value > max) { throw py::value_error( absl::StrCat(name, " ", value, " out of range [", min, ", ", max, "]")); } } void MaybeThrowChildPositionOutOfRange(int position) { if (position < 0 || position > 3) { throw py::value_error( absl::StrCat("Child position ", position, " out of range [0, 3]")); } } void MaybeThrowPositionOutOfRange(uint64_t pos) { if (pos > S2CellId::kMaxPosition) { throw py::value_error( absl::StrCat("pos ", pos, " out of range [0, ", S2CellId::kMaxPosition, "]")); } } // Raise OverflowError if n exceeds Py_ssize_t; otherwise return it cast. // On 32-bit Python, cells() ranges above level ~15 exceed ssize_t max. Py_ssize_t LenOrThrow(int64_t n) { if (n > std::numeric_limits::max()) { throw std::overflow_error(absl::StrCat( "S2CellIdRange size ", n, " exceeds Py_ssize_t max (", std::numeric_limits::max(), ") on this platform. On 32-bit Python, cells() ranges above " "level ~15 exceed ssize_t. Use .size() for the full int64 count.")); } return static_cast(n); } // Normalize a Python-style index (negative counts from end) against a range // of length n and return the 0-based index. Raises IndexError if the index // is still out of [0, n) after normalization. // https://docs.python.org/3/reference/datamodel.html#object.__getitem__ int64_t IndexOrThrow(int64_t i, int64_t n) { if (i < 0) i += n; if (i < 0 || i >= n) throw py::index_error("index out of range"); return i; } // Raise ValueError if the slice step is anything other than 1 (or None). // S2CellIdRange slices must be contiguous; reversed() covers step=-1. void ValidateStepIsOne(py::slice s) { py::object step_obj = s.attr("step"); if (step_obj.is_none()) return; int64_t step = step_obj.cast(); if (step != 1) { throw py::value_error(absl::StrCat( "S2CellIdRange only supports slices with step 1 (got step ", step, ")")); } } // Resolve a Python slice against a range of length n and return the clamped // [start, stop) bounds. Slice indices are silently clamped per: // https://docs.python.org/3/reference/datamodel.html#sequences // // py::slice::compute() is not used because it requires Py_ssize_t, which is // 32-bit on 32-bit platforms; S2CellIdRange can have up to 2^60 cells so // indices are handled as int64_t directly. std::pair ClampedSlice(int64_t n, py::slice s) { auto clamp = [n](int64_t i) -> int64_t { if (i < 0) i += n; if (i < 0) return int64_t{0}; if (i > n) return n; return i; }; py::object start_obj = s.attr("start"); py::object stop_obj = s.attr("stop"); int64_t start = start_obj.is_none() ? int64_t{0} : clamp(start_obj.cast()); int64_t stop = stop_obj.is_none() ? n : clamp(stop_obj.cast()); if (stop < start) stop = start; return {start, stop}; } // Dereference an optional S2CellId from an iterator's next(), or raise // StopIteration if the iterator is exhausted. S2CellId NextOrStop(std::optional result) { if (!result) throw py::stop_iteration(); return *result; } } // namespace void bind_s2cell_id(py::module& m) { auto cls = py::class_(m, "S2CellId", "A 64-bit unsigned integer that uniquely identifies a cell in the\n" "S2 cell decomposition.\n\n" "See s2/s2cell_id.h for comprehensive documentation.") // Constructors .def(py::init([](uint64_t id) { S2CellId cell(id); MaybeThrowNotValid(cell); return cell; }), py::arg("id"), "Construct from a 64-bit cell id.\n\n" "Raises ValueError if the id is not valid.") .def(py::init([](const S2Point& p) { return S2CellId(p); }), py::arg("point"), "Construct a leaf cell containing the given point.\n\n" "The point does not need to be normalized.") .def(py::init([](const S2LatLng& ll) { return S2CellId(ll); }), py::arg("latlng"), "Construct a leaf cell containing the given S2LatLng.") // Factory methods .def_static("from_face", [](int face) { MaybeThrowFaceOutOfRange(face); return S2CellId::FromFace(face); }, py::arg("face"), "Return the cell corresponding to a given S2 cube face (0..5).\n\n" "Raises ValueError if face is out of range.") .def_static("from_face_pos_level", [](int face, uint64_t pos, int level) { MaybeThrowFaceOutOfRange(face); MaybeThrowPositionOutOfRange(pos); MaybeThrowLevelOutOfRange(level, 0, S2CellId::kMaxLevel); return S2CellId::FromFacePosLevel(face, pos, level); }, py::arg("face"), py::arg("pos"), py::arg("level"), "Return a cell given its face, Hilbert curve position, and level.\n\n" "Raises ValueError if face, pos, or level is out of range.") .def_static("from_token", [](const std::string& token) { S2CellId cell = S2CellId::FromToken(token); if (cell == S2CellId::None()) { throw py::value_error( absl::StrCat("Invalid S2CellId token: '", token, "'")); } return cell; }, py::arg("token"), "Return a cell from its token string.\n\n" "Raises ValueError if the token is malformed.") .def_static("from_face_ij", [](int face, int i, int j) { MaybeThrowFaceOutOfRange(face); MaybeThrowCellIdOutOfRange("i", i, 0, S2CellId::kMaxSize - 1); MaybeThrowCellIdOutOfRange("j", j, 0, S2CellId::kMaxSize - 1); return S2CellId::FromFaceIJ(face, i, j); }, py::arg("face"), py::arg("i"), py::arg("j"), "Return a leaf cell given its cube face and (i, j) coordinates") // Properties .def_property_readonly("id", &S2CellId::id, "The 64-bit unique identifier for this cell") // Predicates .def("is_leaf", &S2CellId::is_leaf, "Return true if this is a leaf cell (level == kMaxLevel)") .def("is_face", &S2CellId::is_face, "Return true if this is a top-level face cell (level == 0)") // Geometric operations .def_property_readonly("face", &S2CellId::face, "Which cube face this cell belongs to (0..5)") .def_property_readonly("pos", &S2CellId::pos, "The position along the Hilbert curve over this face") .def_property_readonly("level", &S2CellId::level, "The subdivision level (0..kMaxLevel)") .def("size_ij", py::overload_cast<>(&S2CellId::GetSizeIJ, py::const_), "Return the edge length of this cell in (i,j)-space") .def_static("size_ij_for_level", [](int level) { MaybeThrowLevelOutOfRange(level, 0, S2CellId::kMaxLevel); return S2CellId::GetSizeIJ(level); }, py::arg("level"), "Return the edge length in (i,j)-space of cells at the given level") .def("size_st", py::overload_cast<>(&S2CellId::GetSizeST, py::const_), "Return the edge length of this cell in (s,t)-space") .def_static("size_st_for_level", [](int level) { MaybeThrowLevelOutOfRange(level, 0, S2CellId::kMaxLevel); return S2CellId::GetSizeST(level); }, py::arg("level"), "Return the edge length in (s,t)-space of cells at the given level") .def("to_point", &S2CellId::ToPoint, "Return the center of the cell as a normalized S2Point") .def("to_lat_lng", &S2CellId::ToLatLng, "Return the S2LatLng corresponding to the center of the cell") .def("center_st", &S2CellId::GetCenterST, "Return the center of the cell in (s,t)-space") .def("bound_st", &S2CellId::GetBoundST, "Return the bounds of this cell in (s,t)-space") .def("center_uv", &S2CellId::GetCenterUV, "Return the center of the cell in (u,v)-space") .def("bound_uv", &S2CellId::GetBoundUV, "Return the bounds of this cell in (u,v)-space") .def("child_position", [](S2CellId self) { MaybeThrowLevelOutOfRange(self.level(), 1, S2CellId::kMaxLevel); return self.child_position(); }, "Return the child position (0..3) within this cell's parent.\n\n" "Raises ValueError if level < 1.") .def("child_position_at_level", [](S2CellId self, int level) { MaybeThrowLevelOutOfRange(level, 1, self.level()); return self.child_position(level); }, py::arg("level"), "Return the child position (0..3) of this cell's ancestor at\n" "the given level within its parent.\n\n" "Raises ValueError if level is out of range [1, self.level()].") .def("to_token", &S2CellId::ToToken, "Return a compact token string for this cell.\n\n" "Tokens preserve ordering and the round-trip\n" "from_token(cell.to_token()) == cell is guaranteed.") .def("range_min", &S2CellId::range_min, "Return the minimum cell id contained within this cell") .def("range_max", &S2CellId::range_max, "Return the maximum cell id contained within this cell") .def("contains", &S2CellId::contains, py::arg("other"), "Return true if the given cell is contained within this one") .def("intersects", &S2CellId::intersects, py::arg("other"), "Return true if the given cell intersects this one") .def("common_ancestor_level", &S2CellId::GetCommonAncestorLevel, py::arg("other"), "Return the level of the lowest common ancestor.\n\n" "Returns -1 if the cells are from different faces.") // Traversal .def("parent", [](S2CellId self) { MaybeThrowIfFace(self); return self.parent(); }, "Return the cell at the previous level.\n\n" "Raises ValueError if this is already a face cell.") .def("parent_at_level", [](S2CellId self, int level) { MaybeThrowLevelOutOfRange(level, 0, self.level()); return self.parent(level); }, py::arg("level"), "Return the cell at the given level.\n\n" "Raises ValueError if level is out of range [0, self.level()].") .def("child", [](S2CellId self, int position) { MaybeThrowIfLeaf(self); MaybeThrowChildPositionOutOfRange(position); return self.child(position); }, py::arg("position"), "Return the immediate child at the given position (0..3).\n\n" "Raises ValueError if this is a leaf cell or position is out of range.") .def("children", [](S2CellId self, py::object level_obj) { MaybeThrowIfLeaf(self); S2CellId begin, end; if (level_obj.is_none()) { begin = self.child_begin(); end = self.child_end(); } else { int level = level_obj.cast(); MaybeThrowLevelOutOfRange(level, self.level() + 1, S2CellId::kMaxLevel); begin = self.child_begin(level); end = self.child_end(level); } return S2CellIdRange{begin, end}; }, py::arg("level") = py::none(), "Return a range over the children of this cell.\n\n" "With no argument, returns the 4 immediate children.\n" "With a level argument, returns all descendants at that level.\n" "Raises ValueError if this is a leaf cell or level is out of range.") .def_static("cells", [](int level) { MaybeThrowLevelOutOfRange(level, 0, S2CellId::kMaxLevel); return S2CellIdRange{S2CellId::Begin(level), S2CellId::End(level)}; }, py::arg("level"), "Return a range over all cells at the given level across all 6 faces.\n\n" "Warning: the number of cells grows as 6 * 4^level.") .def("edge_neighbors", [](S2CellId self) { S2CellId neighbors[4]; self.GetEdgeNeighbors(neighbors); return py::make_tuple(neighbors[0], neighbors[1], neighbors[2], neighbors[3]); }, "Return the four cells adjacent across this cell's edges") .def("vertex_neighbors", [](S2CellId self, int level) { MaybeThrowIfFace(self); MaybeThrowLevelOutOfRange(level, 0, self.level() - 1); std::vector output; self.AppendVertexNeighbors(level, &output); return output; }, py::arg("level"), "Return the neighbors of the closest vertex at the given level.\n\n" "Normally returns 4 neighbors, but may return 3 for cube vertices.\n" "Raises ValueError if level >= self.level().") .def("all_neighbors", [](S2CellId self, int level) { MaybeThrowLevelOutOfRange(level, self.level(), S2CellId::kMaxLevel); std::vector output; self.AppendAllNeighbors(level, &output); return output; }, py::arg("level"), "Return all neighbors of this cell at the given level.\n\n" "Raises ValueError if level < self.level().") // Operators .def(py::self == py::self, "Return true if cell ids are equal") .def(py::self != py::self, "Return true if cell ids are not equal") .def(py::self < py::self, "Compare cell ids by their numeric value") .def(py::self > py::self, "Compare cell ids by their numeric value") .def(py::self <= py::self, "Compare cell ids by their numeric value") .def(py::self >= py::self, "Compare cell ids by their numeric value") .def("__hash__", [](S2CellId self) { return absl::Hash()(self); }) // String representation .def("__repr__", [](S2CellId id) { std::ostringstream oss; oss << "S2CellId(" << id << ")"; return oss.str(); }) .def("__str__", [](S2CellId id) { std::ostringstream oss; oss << id; return oss.str(); }); cls.attr("MAX_LEVEL") = S2CellId::kMaxLevel; cls.attr("MAX_POSITION") = S2CellId::kMaxPosition; cls.attr("NUM_FACES") = S2CellId::kNumFaces; py::class_(m, "S2CellIdRange", "A range of S2CellIds at the same level along the Hilbert curve.\n\n" "Supports len(), indexing, slicing, iteration, reversed(), and 'in'.\n" "Returned from S2CellId.children() and S2CellId.cells().\n\n" "Slicing: only step=1 is supported. Use reversed() for step=-1.\n" "Other step values raise ValueError.") .def("__len__", [](const S2CellIdRange& self) { return LenOrThrow(self.size()); }) .def("size", &S2CellIdRange::size, "Return the number of cells in the range as a 64-bit integer.\n\n" "Equivalent to len() on 64-bit platforms; use this method when\n" "the range may exceed Py_ssize_t (e.g. very large cells() ranges\n" "on 32-bit Python).") .def("__getitem__", [](const S2CellIdRange& self, int64_t i) { return self.at(IndexOrThrow(i, self.size())); }, py::arg("index")) .def("__getitem__", [](const S2CellIdRange& self, py::slice s) { ValidateStepIsOne(s); auto [start, stop] = ClampedSlice(self.size(), s); return self.slice(start, stop); }, py::arg("slice")) .def("__contains__", &S2CellIdRange::contains, py::arg("cell")) .def("__eq__", [](const S2CellIdRange& self, const S2CellIdRange& other) { return self.begin == other.begin && self.end == other.end; }, py::arg("other")) .def("__repr__", [](const S2CellIdRange& self) { std::ostringstream oss; oss << "S2CellIdRange(begin=" << self.begin.id() << ", end=" << self.end.id() << ")"; return oss.str(); }) .def("__iter__", [](const S2CellIdRange& self) { return S2CellIdForwardIterator{self.begin, self.end}; }) .def("__reversed__", [](const S2CellIdRange& self) { return S2CellIdReverseIterator{self.end, self.begin}; }); py::class_(m, "_S2CellIdForwardIterator", py::module_local()) .def("__iter__", [](S2CellIdForwardIterator& self) -> S2CellIdForwardIterator& { return self; }) .def("__next__", [](S2CellIdForwardIterator& self) { return NextOrStop(self.next()); }); py::class_(m, "_S2CellIdReverseIterator", py::module_local()) .def("__iter__", [](S2CellIdReverseIterator& self) -> S2CellIdReverseIterator& { return self; }) .def("__next__", [](S2CellIdReverseIterator& self) { return NextOrStop(self.next()); }); } src/python/s2cell_id_range.cc000066400000000000000000000032161524103652300165140ustar00rootroot00000000000000// Copyright 2026 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #include "python/s2cell_id_range.h" #include "absl/log/absl_check.h" int64_t S2CellIdRange::size() const { ABSL_DCHECK(begin == end || begin.level() == end.level()) << "S2CellIdRange: begin and end must be at the same level"; return end.distance_from_begin() - begin.distance_from_begin(); } S2CellId S2CellIdRange::at(int64_t i) const { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, size()); return begin.advance(i); } S2CellIdRange S2CellIdRange::slice(int64_t start, int64_t stop) const { ABSL_DCHECK_GE(start, 0); ABSL_DCHECK_LE(start, stop); ABSL_DCHECK_LE(stop, size()); return S2CellIdRange{begin.advance(start), begin.advance(stop)}; } bool S2CellIdRange::contains(S2CellId cell) const { return cell >= begin && cell < end && cell.level() == begin.level(); } std::optional S2CellIdForwardIterator::next() { if (cur == end) return std::nullopt; S2CellId result = cur; cur = cur.next(); return result; } std::optional S2CellIdReverseIterator::next() { if (cur == begin) return std::nullopt; cur = cur.prev(); return cur; } src/python/s2cell_id_range.h000066400000000000000000000050371524103652300163610ustar00rootroot00000000000000// Copyright 2026 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // Helpers for S2CellId sequence iteration used by Python bindings. // // S2CellIdRange represents a contiguous range of S2CellIds at a fixed level, // with forward and reverse iterators. These types are exposed to pybind11 to // support Python's sequence protocol (len, indexing, slicing, iteration, // reversed) on S2CellId ranges returned by methods such as children() and // cells(). #ifndef PYTHON_S2CELL_ID_RANGE_H_ #define PYTHON_S2CELL_ID_RANGE_H_ #include #include #include "s2/s2cell_id.h" // A contiguous half-open range [begin, end) of S2CellIds at the same level // along the Hilbert curve. All operations are O(1). The range may be empty // (begin == end). struct S2CellIdRange { S2CellId begin; S2CellId end; // Return the number of cells in the range. int64_t size() const; // Return the cell at 0-based offset i. i must be in [0, size()); behavior // is undefined otherwise. S2CellId at(int64_t i) const; // Return the sub-range [start, stop). start and stop must satisfy // 0 <= start <= stop <= size(); behavior is undefined otherwise. S2CellIdRange slice(int64_t start, int64_t stop) const; // Return true if cell is in the range and at the same level as begin. bool contains(S2CellId cell) const; }; // Forward iterator over an S2CellIdRange. struct S2CellIdForwardIterator { S2CellId cur; S2CellId end; // Return the next cell and advance, or std::nullopt if exhausted. std::optional next(); }; // Reverse iterator over an S2CellIdRange. Construct with cur = range.end; // next() decrements cur before yielding, so the empty-range case (begin == // end) is handled without a separate flag. struct S2CellIdReverseIterator { S2CellId cur; // one-past-current; starts at range.end S2CellId begin; // stop when cur reaches here // Return the next cell (in reverse order) and advance, or std::nullopt if // exhausted. std::optional next(); }; #endif // PYTHON_S2CELL_ID_RANGE_H_ src/python/s2cell_id_range_test.cc000066400000000000000000000173171524103652300175620ustar00rootroot00000000000000// Copyright 2026 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #include "python/s2cell_id_range.h" #include #include #include #include "s2/s2cell_id.h" namespace { // Convenience: range of all cells at a given level on a single face. S2CellIdRange FaceRange(int face, int level) { S2CellId f = S2CellId::FromFace(face); return S2CellIdRange{f.child_begin(level), f.child_end(level)}; } // Collect all cells produced by iterating a range forward. std::vector Collect(S2CellIdRange r) { std::vector result; S2CellIdForwardIterator it{r.begin, r.end}; while (std::optional cell = it.next()) { result.push_back(*cell); } return result; } // Collect all cells produced by iterating a range in reverse. std::vector CollectReverse(S2CellIdRange r) { std::vector result; S2CellIdReverseIterator rit{r.end, r.begin}; while (std::optional cell = rit.next()) { result.push_back(*cell); } return result; } // --------------------------------------------------------------------------- // S2CellIdRange::size // --------------------------------------------------------------------------- TEST(S2CellIdRangeTest, SizeEmptyRange) { S2CellId face = S2CellId::FromFace(0); S2CellIdRange r{face.child_begin(1), face.child_begin(1)}; EXPECT_EQ(r.size(), 0); } TEST(S2CellIdRangeTest, SizeFaceLevel1) { // Each face has 4 level-1 children. S2CellIdRange r = FaceRange(0, 1); EXPECT_EQ(r.size(), 4); } TEST(S2CellIdRangeTest, SizeFaceLevel2) { // Each face has 16 level-2 children. S2CellIdRange r = FaceRange(0, 2); EXPECT_EQ(r.size(), 16); } TEST(S2CellIdRangeTest, SizeAllFacesLevel0) { S2CellIdRange r{S2CellId::Begin(0), S2CellId::End(0)}; EXPECT_EQ(r.size(), 6); } // --------------------------------------------------------------------------- // S2CellIdRange::at // --------------------------------------------------------------------------- TEST(S2CellIdRangeTest, AtFirstCell) { S2CellIdRange r = FaceRange(0, 1); EXPECT_EQ(r.at(0), r.begin); } TEST(S2CellIdRangeTest, AtLastCell) { S2CellIdRange r = FaceRange(0, 1); EXPECT_EQ(r.at(3), r.begin.advance(3)); } TEST(S2CellIdRangeTest, AtMiddleCell) { S2CellIdRange r = FaceRange(0, 2); EXPECT_EQ(r.at(7), r.begin.advance(7)); } // --------------------------------------------------------------------------- // S2CellIdRange::slice // --------------------------------------------------------------------------- TEST(S2CellIdRangeTest, SliceFullRange) { S2CellIdRange r = FaceRange(0, 1); S2CellIdRange s = r.slice(0, 4); EXPECT_EQ(s.begin, r.begin); EXPECT_EQ(s.end, r.end); } TEST(S2CellIdRangeTest, SliceFirstTwo) { S2CellIdRange r = FaceRange(0, 1); S2CellIdRange s = r.slice(0, 2); EXPECT_EQ(s.size(), 2); EXPECT_EQ(s.begin, r.begin); EXPECT_EQ(s.end, r.begin.advance(2)); } TEST(S2CellIdRangeTest, SliceLastTwo) { S2CellIdRange r = FaceRange(0, 1); S2CellIdRange s = r.slice(2, 4); EXPECT_EQ(s.size(), 2); EXPECT_EQ(s.begin, r.begin.advance(2)); EXPECT_EQ(s.end, r.end); } TEST(S2CellIdRangeTest, SliceEmpty) { S2CellIdRange r = FaceRange(0, 1); S2CellIdRange s = r.slice(2, 2); EXPECT_EQ(s.size(), 0); EXPECT_EQ(s.begin, s.end); } TEST(S2CellIdRangeTest, SliceSingleCell) { S2CellIdRange r = FaceRange(0, 1); S2CellIdRange s = r.slice(1, 2); EXPECT_EQ(s.size(), 1); EXPECT_EQ(s.at(0), r.begin.advance(1)); } // --------------------------------------------------------------------------- // S2CellIdRange::contains // --------------------------------------------------------------------------- TEST(S2CellIdRangeTest, ContainsCellInRange) { S2CellIdRange r = FaceRange(0, 1); EXPECT_TRUE(r.contains(r.begin)); EXPECT_TRUE(r.contains(r.begin.advance(1))); EXPECT_TRUE(r.contains(r.begin.advance(3))); } TEST(S2CellIdRangeTest, ContainsExcludesEnd) { S2CellIdRange r = FaceRange(0, 1); EXPECT_FALSE(r.contains(r.end)); } TEST(S2CellIdRangeTest, ContainsCellFromDifferentFace) { S2CellIdRange r = FaceRange(0, 1); S2CellId other = S2CellId::FromFace(1).child_begin(1); EXPECT_FALSE(r.contains(other)); } TEST(S2CellIdRangeTest, ContainsCellAtWrongLevel) { S2CellIdRange r = FaceRange(0, 1); // A level-2 cell that falls within the level-1 range bounds should not match. S2CellId level2 = r.begin.child_begin(); EXPECT_FALSE(r.contains(level2)); } TEST(S2CellIdRangeTest, ContainsEmptyRange) { S2CellId face = S2CellId::FromFace(0); S2CellIdRange r{face.child_begin(1), face.child_begin(1)}; EXPECT_FALSE(r.contains(face.child_begin(1))); } // --------------------------------------------------------------------------- // S2CellIdForwardIterator // --------------------------------------------------------------------------- TEST(S2CellIdForwardIteratorTest, IteratesAllCells) { S2CellIdRange r = FaceRange(0, 1); std::vector cells = Collect(r); ASSERT_EQ(cells.size(), 4u); for (int i = 0; i < 4; ++i) { EXPECT_EQ(cells[i], r.begin.advance(i)); } } TEST(S2CellIdForwardIteratorTest, EmptyRangeProducesNoItems) { S2CellId face = S2CellId::FromFace(0); S2CellIdRange r{face.child_begin(1), face.child_begin(1)}; EXPECT_TRUE(Collect(r).empty()); } TEST(S2CellIdForwardIteratorTest, ReturnsNulloptWhenExhausted) { S2CellIdRange r = FaceRange(0, 1); S2CellIdForwardIterator it{r.begin, r.end}; for (int i = 0; i < 4; ++i) it.next(); EXPECT_EQ(it.next(), std::nullopt); // Calling next() again is safe. EXPECT_EQ(it.next(), std::nullopt); } // --------------------------------------------------------------------------- // S2CellIdReverseIterator // --------------------------------------------------------------------------- TEST(S2CellIdReverseIteratorTest, IteratesAllCellsInReverse) { S2CellIdRange r = FaceRange(0, 1); std::vector cells = CollectReverse(r); ASSERT_EQ(cells.size(), 4u); for (int i = 0; i < 4; ++i) { EXPECT_EQ(cells[i], r.begin.advance(3 - i)); } } TEST(S2CellIdReverseIteratorTest, EmptyRangeProducesNoItems) { S2CellId face = S2CellId::FromFace(0); S2CellIdRange r{face.child_begin(1), face.child_begin(1)}; EXPECT_TRUE(CollectReverse(r).empty()); } TEST(S2CellIdReverseIteratorTest, SingleCellRange) { S2CellIdRange r = FaceRange(0, 1); S2CellIdRange single = r.slice(2, 3); std::vector cells = CollectReverse(single); ASSERT_EQ(cells.size(), 1u); EXPECT_EQ(cells[0], single.at(0)); } TEST(S2CellIdReverseIteratorTest, ReturnsNulloptWhenExhausted) { S2CellIdRange r = FaceRange(0, 1); S2CellIdReverseIterator it{r.end, r.begin}; for (int i = 0; i < 4; ++i) it.next(); EXPECT_EQ(it.next(), std::nullopt); EXPECT_EQ(it.next(), std::nullopt); } // --------------------------------------------------------------------------- // Round-trip: forward then reverse produces symmetric sequences // --------------------------------------------------------------------------- TEST(S2CellIdRangeTest, ForwardAndReverseAreSymmetric) { S2CellIdRange r = FaceRange(2, 2); // 16 cells on face 2 std::vector fwd = Collect(r); std::vector rev = CollectReverse(r); ASSERT_EQ(fwd.size(), rev.size()); for (size_t i = 0; i < fwd.size(); ++i) { EXPECT_EQ(fwd[i], rev[fwd.size() - 1 - i]); } } } // namespace src/python/s2cell_id_test.py000066400000000000000000000447551524103652300164570ustar00rootroot00000000000000"""Tests for S2CellId pybind11 bindings.""" import unittest import s2geometry_pybind as s2 class TestS2CellId(unittest.TestCase): """Test cases for S2CellId bindings.""" # Constructors def test_constructor_from_point(self): p = s2.S2Point(1.0, 0.0, 0.0) cell = s2.S2CellId(p) self.assertTrue(cell.is_leaf()) def test_constructor_from_latlng(self): ll = s2.S2LatLng.from_degrees(0.0, 0.0) cell = s2.S2CellId(ll) self.assertTrue(cell.is_leaf()) def test_constructor_from_uint64(self): # Construct from a face cell, then use its id to reconstruct. face_cell = s2.S2CellId.from_face(0) cell = s2.S2CellId(face_cell.id) self.assertEqual(cell, face_cell) def test_constructor_from_invalid_uint64_raises(self): with self.assertRaises(ValueError): s2.S2CellId(0) # Constants def test_max_level(self): self.assertEqual(s2.S2CellId.MAX_LEVEL, 30) def test_num_faces(self): self.assertEqual(s2.S2CellId.NUM_FACES, 6) # Factory methods def test_from_face(self): for face in range(6): cell = s2.S2CellId.from_face(face) self.assertEqual(cell.face, face) self.assertTrue(cell.is_face()) def test_from_face_out_of_range_raises(self): with self.assertRaises(ValueError) as cm: s2.S2CellId.from_face(6) self.assertEqual(str(cm.exception), "Face 6 out of range [0, 5]") with self.assertRaises(ValueError): s2.S2CellId.from_face(-1) def test_from_face_pos_level(self): cell = s2.S2CellId.from_face_pos_level(0, 0, 0) self.assertEqual(cell.level, 0) self.assertEqual(cell.face, 0) def test_from_face_pos_level_pos_out_of_range_raises(self): with self.assertRaises(ValueError): s2.S2CellId.from_face_pos_level(0, s2.S2CellId.MAX_POSITION + 1, 0) def test_from_token_roundtrip(self): cell = s2.S2CellId.from_face(3) token = cell.to_token() self.assertEqual(token, "7") cell2 = s2.S2CellId.from_token(token) self.assertEqual(cell, cell2) def test_from_token_invalid_raises(self): with self.assertRaises(ValueError) as cm: s2.S2CellId.from_token("invalid_token") self.assertEqual(str(cm.exception), "Invalid S2CellId token: 'invalid_token'") def test_from_face_ij(self): cell = s2.S2CellId.from_face_ij(0, 0, 0) self.assertTrue(cell.is_leaf()) def test_from_face_ij_i_out_of_range_raises(self): with self.assertRaises(ValueError): s2.S2CellId.from_face_ij(0, -1, 0) with self.assertRaises(ValueError): s2.S2CellId.from_face_ij(0, 1 << s2.S2CellId.MAX_LEVEL, 0) def test_from_face_ij_j_out_of_range_raises(self): with self.assertRaises(ValueError): s2.S2CellId.from_face_ij(0, 0, -1) with self.assertRaises(ValueError): s2.S2CellId.from_face_ij(0, 0, 1 << s2.S2CellId.MAX_LEVEL) # Properties def test_id_property(self): cell = s2.S2CellId.from_face(0) self.assertIsInstance(cell.id, int) self.assertGreater(cell.id, 0) # Predicates def test_is_leaf(self): p = s2.S2Point(1.0, 0.0, 0.0) leaf = s2.S2CellId(p) self.assertTrue(leaf.is_leaf()) face = s2.S2CellId.from_face(0) self.assertFalse(face.is_leaf()) def test_is_face(self): face = s2.S2CellId.from_face(0) self.assertTrue(face.is_face()) child = face.child(0) self.assertFalse(child.is_face()) # Geometric operations def test_face(self): for f in range(6): self.assertEqual(s2.S2CellId.from_face(f).face, f) def test_level(self): face = s2.S2CellId.from_face(0) self.assertEqual(face.level, 0) child = face.child(0) self.assertEqual(child.level, 1) def test_to_point(self): cell = s2.S2CellId.from_face(0) p = cell.to_point() # Face 0 center is approximately (1, 0, 0). self.assertAlmostEqual(p.x, 1.0, places=1) self.assertAlmostEqual(p.y, 0.0, places=1) self.assertAlmostEqual(p.z, 0.0, places=1) def test_to_lat_lng(self): ll = s2.S2LatLng.from_degrees(45.0, 90.0) cell = s2.S2CellId(ll) ll2 = cell.to_lat_lng() # The cell center may not exactly match the original point due to # quantization to the cell center. self.assertAlmostEqual(ll.lat.degrees, ll2.lat.degrees, places=5) self.assertAlmostEqual(ll.lng.degrees, ll2.lng.degrees, places=5) def test_center_st(self): # (s,t)-space covers [0,1] x [0,1] per face; a face cell's center # is at (0.5, 0.5). st = s2.S2CellId.from_face(0).center_st() self.assertAlmostEqual(st.x, 0.5) self.assertAlmostEqual(st.y, 0.5) def test_bound_st(self): # A face cell in (s,t) spans the full [0,1] x [0,1] range. bound = s2.S2CellId.from_face(0).bound_st() self.assertAlmostEqual(bound.lo.x, 0.0) self.assertAlmostEqual(bound.lo.y, 0.0) self.assertAlmostEqual(bound.hi.x, 1.0) self.assertAlmostEqual(bound.hi.y, 1.0) def test_center_uv(self): # (u,v)-space covers [-1,1] x [-1,1] per face; a face cell's center # is at the origin. uv = s2.S2CellId.from_face(0).center_uv() self.assertAlmostEqual(uv.x, 0.0) self.assertAlmostEqual(uv.y, 0.0) def test_bound_uv(self): # A face cell in (u,v) spans the full [-1,1] x [-1,1] range. bound = s2.S2CellId.from_face(0).bound_uv() self.assertAlmostEqual(bound.lo.x, -1.0) self.assertAlmostEqual(bound.lo.y, -1.0) self.assertAlmostEqual(bound.hi.x, 1.0) self.assertAlmostEqual(bound.hi.y, 1.0) def test_size_ij(self): # In (i,j)-space a face spans 2^kMaxLevel = 2^30 units. face = s2.S2CellId.from_face(0) self.assertEqual(face.size_ij(), 1 << s2.S2CellId.MAX_LEVEL) def test_size_ij_for_level(self): # Level 0 cells span 2^kMaxLevel in (i,j); leaf cells span 1. self.assertEqual(s2.S2CellId.size_ij_for_level(0), 1 << s2.S2CellId.MAX_LEVEL) self.assertEqual(s2.S2CellId.size_ij_for_level(30), 1) def test_size_st(self): # In (s,t)-space a face spans the full unit interval, so size is 1.0. self.assertAlmostEqual(s2.S2CellId.from_face(0).size_st(), 1.0) def test_size_st_for_level(self): # Level-0 cells span the full unit interval; level-30 cells span 1/2^30. self.assertAlmostEqual(s2.S2CellId.size_st_for_level(0), 1.0) self.assertAlmostEqual(s2.S2CellId.size_st_for_level(30), 1.0 / (1 << 30)) def test_child_position(self): face = s2.S2CellId.from_face(0) for pos in range(4): child = face.child(pos) self.assertEqual(child.child_position(), pos) def test_child_position_face_cell_raises(self): face = s2.S2CellId.from_face(0) with self.assertRaises(ValueError) as cm: face.child_position() self.assertEqual(str(cm.exception), "Level 0 out of range [1, 30]") def test_child_position_at_level(self): cell = s2.S2CellId.from_face(0).child(0).child(1).child(2) self.assertEqual(cell.child_position_at_level(1), 0) self.assertEqual(cell.child_position_at_level(2), 1) self.assertEqual(cell.child_position_at_level(3), 2) def test_to_token(self): cell = s2.S2CellId.from_face(0) self.assertEqual(cell.to_token(), "1") def test_range_min_max_leaf(self): # A leaf cell's range is just itself. leaf = s2.S2CellId(s2.S2Point(1.0, 0.0, 0.0)) self.assertEqual(leaf.range_min(), leaf) self.assertEqual(leaf.range_max(), leaf) def test_range_min_max_covers_children(self): # range_min/range_max bound the leaf cells of this cell; every # direct child's range must sit within the parent's range. face = s2.S2CellId.from_face(0) self.assertLess(face.range_min(), face.range_max()) children = [face.child(i) for i in range(4)] for child in children: self.assertGreaterEqual(child.range_min(), face.range_min()) self.assertLessEqual(child.range_max(), face.range_max()) # The first child's range_min equals the parent's, and likewise # the last child's range_max equals the parent's. self.assertEqual(children[0].range_min(), face.range_min()) self.assertEqual(children[-1].range_max(), face.range_max()) def test_contains(self): face = s2.S2CellId.from_face(0) child = face.child(0) self.assertTrue(face.contains(child)) self.assertFalse(child.contains(face)) def test_intersects(self): face = s2.S2CellId.from_face(0) child = face.child(0) self.assertTrue(face.intersects(child)) self.assertTrue(child.intersects(face)) # Different faces don't intersect. face1 = s2.S2CellId.from_face(1) self.assertFalse(face.intersects(face1)) def test_common_ancestor_level(self): # Two cells sharing the first two Hilbert curve steps on face 0 # diverge at level 2, so their common ancestor is at level 2. base = s2.S2CellId.from_face(0).child(0).child(1) cell1 = base.child(2) cell2 = base.child(3) self.assertEqual(cell1.common_ancestor_level(cell2), 2) def test_common_ancestor_level_different_faces(self): cell1 = s2.S2CellId.from_face(0) cell2 = s2.S2CellId.from_face(1) self.assertEqual(cell1.common_ancestor_level(cell2), -1) # Traversal def test_parent(self): face = s2.S2CellId.from_face(0) child = face.child(0) self.assertEqual(child.parent(), face) def test_parent_of_face_raises(self): face = s2.S2CellId.from_face(0) with self.assertRaises(ValueError) as cm: face.parent() self.assertEqual(str(cm.exception), "Function invalid for face cells") def test_parent_at_level(self): cell = s2.S2CellId.from_face(0).child(0).child(1).child(2) self.assertEqual(cell.parent_at_level(0), s2.S2CellId.from_face(0)) self.assertEqual(cell.parent_at_level(3), cell) def test_child(self): face = s2.S2CellId.from_face(0) for pos in range(4): child = face.child(pos) self.assertEqual(child.level, 1) def test_child_of_leaf_raises(self): leaf = s2.S2CellId(s2.S2Point(1.0, 0.0, 0.0)) with self.assertRaises(ValueError) as cm: leaf.child(0) self.assertEqual(str(cm.exception), "Function invalid for leaf cells") def test_child_position_out_of_range_raises(self): face = s2.S2CellId.from_face(0) with self.assertRaises(ValueError) as cm: face.child(4) self.assertEqual(str(cm.exception), "Child position 4 out of range [0, 3]") def test_children(self): face = s2.S2CellId.from_face(0) children = list(face.children()) self.assertEqual(len(children), 4) for child in children: self.assertEqual(child.level, 1) def test_children_positions(self): face = s2.S2CellId.from_face(0) children = list(face.children()) for i, child in enumerate(children): self.assertEqual(child.child_position(), i) def test_children_at_level(self): face = s2.S2CellId.from_face(0) # Level 2 descendants = 4^2 = 16 cells. children = list(face.children(2)) self.assertEqual(len(children), 16) for child in children: self.assertEqual(child.level, 2) def test_children_of_leaf_raises(self): leaf = s2.S2CellId(s2.S2Point(1.0, 0.0, 0.0)) with self.assertRaises(ValueError) as cm: list(leaf.children()) self.assertEqual(str(cm.exception), "Function invalid for leaf cells") def test_children_at_own_level_raises(self): cell = s2.S2CellId.from_face(0) with self.assertRaises(ValueError): cell.children(0) def test_cells_level_0(self): cells = list(s2.S2CellId.cells(0)) self.assertEqual(len(cells), 6) for i, cell in enumerate(cells): self.assertEqual(cell.face, i) def test_cells_level_1(self): cells = list(s2.S2CellId.cells(1)) # 6 faces * 4 children = 24 cells. self.assertEqual(len(cells), 24) for cell in cells: self.assertEqual(cell.level, 1) def test_cells_level_out_of_range_raises(self): with self.assertRaises(ValueError) as cm: s2.S2CellId.cells(31) self.assertEqual(str(cm.exception), "Level 31 out of range [0, 30]") def test_edge_neighbors(self): cell = s2.S2CellId.from_face(0) neighbors = cell.edge_neighbors() self.assertEqual(len(neighbors), 4) def test_vertex_neighbors(self): cell = s2.S2CellId.from_face(0).child(0).child(1).child(2) neighbors = cell.vertex_neighbors(1) self.assertGreaterEqual(len(neighbors), 3) self.assertLessEqual(len(neighbors), 4) def test_vertex_neighbors_face_cell_raises(self): face = s2.S2CellId.from_face(0) with self.assertRaises(ValueError): face.vertex_neighbors(0) def test_vertex_neighbors_level_out_of_range_raises(self): cell = s2.S2CellId.from_face(0).child(0).child(1).child(2) with self.assertRaises(ValueError): cell.vertex_neighbors(3) # level must be < self.level() (3) def test_all_neighbors(self): cell = s2.S2CellId.from_face(0).child(0) neighbors = cell.all_neighbors(1) self.assertGreater(len(neighbors), 0) # Operators def test_equality(self): a = s2.S2CellId.from_face(0) b = s2.S2CellId.from_face(0) c = s2.S2CellId.from_face(1) self.assertTrue(a == b) self.assertTrue(a != c) def test_comparison(self): a = s2.S2CellId.from_face(0) b = s2.S2CellId.from_face(1) self.assertTrue(a < b) self.assertTrue(b > a) self.assertTrue(a <= a) self.assertTrue(a >= a) def test_hash(self): a = s2.S2CellId.from_face(0) b = s2.S2CellId.from_face(0) self.assertEqual(hash(a), hash(b)) # Can be used in sets/dicts. s = {a, b} self.assertEqual(len(s), 1) # String representation def test_repr(self): cell = s2.S2CellId.from_face(0) self.assertEqual(repr(cell), "S2CellId(0/)") def test_str(self): cell = s2.S2CellId.from_face(0) self.assertEqual(str(cell), "0/") def test_repr_child(self): cell = s2.S2CellId.from_face(3).child(0).child(2) self.assertEqual(repr(cell), "S2CellId(3/02)") class TestS2CellIdRange(unittest.TestCase): """Test cases for the S2CellIdRange class returned by children()/cells().""" def test_len(self): face = s2.S2CellId.from_face(0) self.assertEqual(len(face.children()), 4) self.assertEqual(len(face.children(2)), 16) def test_size_matches_len(self): face = s2.S2CellId.from_face(0) self.assertEqual(face.children().size(), 4) self.assertEqual(s2.S2CellId.cells(1).size(), 24) def test_size_large_range(self): # cells(20) = 6 * 4^20 ≈ 6.6e12; fits in int64 but iterating would # be prohibitive. size() returns it without materializing. self.assertEqual(s2.S2CellId.cells(20).size(), 6 * (4 ** 20)) def test_getitem(self): face = s2.S2CellId.from_face(0) children = face.children() self.assertEqual(children[0].child_position(), 0) self.assertEqual(children[3].child_position(), 3) # Negative indexing. self.assertEqual(children[-1].child_position(), 3) def test_getitem_out_of_range_raises(self): children = s2.S2CellId.from_face(0).children() with self.assertRaises(IndexError): children[4] with self.assertRaises(IndexError): children[-5] def test_slice_basic(self): face = s2.S2CellId.from_face(0) children = face.children() sliced = children[1:3] self.assertEqual(len(sliced), 2) self.assertEqual(list(sliced), [face.child(1), face.child(2)]) def test_slice_open_ended(self): face = s2.S2CellId.from_face(0) children = face.children() self.assertEqual(list(children[:2]), [face.child(0), face.child(1)]) self.assertEqual(list(children[2:]), [face.child(2), face.child(3)]) self.assertEqual(list(children[:]), list(children)) def test_slice_negative_indices(self): face = s2.S2CellId.from_face(0) children = face.children() self.assertEqual(list(children[-2:]), [face.child(2), face.child(3)]) def test_slice_clamps_out_of_range(self): children = s2.S2CellId.from_face(0).children() # Stop past the end is clamped. self.assertEqual(len(children[0:100]), 4) # Start past the end produces an empty range. self.assertEqual(len(children[100:]), 0) def test_slice_step_not_one_raises(self): children = s2.S2CellId.from_face(0).children() with self.assertRaises(ValueError) as cm: children[::2] self.assertIn("step 1", str(cm.exception)) with self.assertRaises(ValueError): children[::-1] def test_slice_returns_range(self): # Slicing returns another S2CellIdRange, not a list. children = s2.S2CellId.from_face(0).children() sliced = children[1:3] self.assertIsInstance(sliced, s2.S2CellIdRange) def test_contains(self): face = s2.S2CellId.from_face(0) children = face.children() child0 = face.child(0) self.assertIn(child0, children) # A cell from a different face is not in the range. other = s2.S2CellId.from_face(1).child(0) self.assertNotIn(other, children) # A cell at the wrong level is not in the range. self.assertNotIn(face, children) def test_reversed(self): face = s2.S2CellId.from_face(0) children = list(face.children()) rev_children = list(reversed(face.children())) self.assertEqual(rev_children, list(reversed(children))) if __name__ == "__main__": unittest.main() src/python/s2cell_test.py000066400000000000000000000306611524103652300157720ustar00rootroot00000000000000"""Tests for S2Cell pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS2Cell(unittest.TestCase): """Test cases for S2Cell bindings.""" # Constructors def test_constructor_from_cell_id(self): cell_id = s2.S2CellId.from_face(0) cell = s2.S2Cell(cell_id) self.assertEqual(cell.id, cell_id) self.assertEqual(cell.face, 0) self.assertEqual(cell.level, 0) def test_constructor_from_point(self): p = s2.S2Point(1.0, 0.0, 0.0) cell = s2.S2Cell(p) self.assertTrue(cell.is_leaf()) def test_constructor_from_latlng(self): ll = s2.S2LatLng.from_degrees(0.0, 0.0) cell = s2.S2Cell(ll) self.assertTrue(cell.is_leaf()) # Factory methods def test_from_face(self): for face in range(6): cell = s2.S2Cell.from_face(face) self.assertEqual(cell.face, face) self.assertEqual(cell.level, 0) def test_from_face_out_of_range_raises(self): with self.assertRaises(ValueError) as cm: s2.S2Cell.from_face(6) self.assertEqual(str(cm.exception), "Face 6 out of range [0, 5]") with self.assertRaises(ValueError): s2.S2Cell.from_face(-1) def test_from_face_pos_level(self): cell = s2.S2Cell.from_face_pos_level(0, 0, 0) self.assertEqual(cell.level, 0) self.assertEqual(cell.face, 0) def test_from_face_pos_level_out_of_range_raises(self): with self.assertRaises(ValueError): s2.S2Cell.from_face_pos_level(6, 0, 0) with self.assertRaises(ValueError): s2.S2Cell.from_face_pos_level(0, s2.S2CellId.MAX_POSITION + 1, 0) with self.assertRaises(ValueError): s2.S2Cell.from_face_pos_level(0, 0, 31) # Constants def test_boundary_constants(self): self.assertEqual(int(s2.S2Cell.BOTTOM_EDGE), 0) self.assertEqual(int(s2.S2Cell.RIGHT_EDGE), 1) self.assertEqual(int(s2.S2Cell.TOP_EDGE), 2) self.assertEqual(int(s2.S2Cell.LEFT_EDGE), 3) # Properties def test_id(self): cell_id = s2.S2CellId.from_face(3) cell = s2.S2Cell(cell_id) self.assertEqual(cell.id, cell_id) def test_face(self): for f in range(6): self.assertEqual(s2.S2Cell.from_face(f).face, f) def test_level(self): face = s2.S2Cell.from_face(0) self.assertEqual(face.level, 0) child = s2.S2Cell(face.id.child(0)) self.assertEqual(child.level, 1) def test_orientation(self): # Orientation is a bitmask in [0, 3]. for f in range(6): self.assertIn(s2.S2Cell.from_face(f).orientation, range(4)) child = s2.S2Cell(s2.S2CellId.from_face(0).child(0)) self.assertIn(child.orientation, range(4)) # Predicates def test_is_leaf(self): face = s2.S2Cell.from_face(0) self.assertFalse(face.is_leaf()) leaf = s2.S2Cell(s2.S2Point(1.0, 0.0, 0.0)) self.assertTrue(leaf.is_leaf()) # Geometric operations def test_size_ij(self): # A face cell spans 2^kMaxLevel in (i,j). face = s2.S2Cell.from_face(0) self.assertEqual(face.size_ij(), 1 << s2.S2CellId.MAX_LEVEL) def test_size_st(self): # A face cell spans the full [0,1] range in (s,t). face = s2.S2Cell.from_face(0) self.assertAlmostEqual(face.size_st(), 1.0) def test_vertex_count_and_normalization(self): face = s2.S2Cell.from_face(0) for k in range(4): v = face.vertex(k) # Normalized vertices should have unit norm. self.assertAlmostEqual(v.norm(), 1.0) def test_vertex_mod_4(self): face = s2.S2Cell.from_face(0) # Argument is reduced modulo 4. v0 = face.vertex(0) v4 = face.vertex(4) self.assertAlmostEqual(v0.x, v4.x) self.assertAlmostEqual(v0.y, v4.y) self.assertAlmostEqual(v0.z, v4.z) def test_edge(self): face = s2.S2Cell.from_face(0) for k in range(4): e = face.edge(k) self.assertAlmostEqual(e.norm(), 1.0) def test_uv_coord_of_edge(self): face = s2.S2Cell.from_face(0) # Face cell UV bounds are [-1, 1] x [-1, 1]. Bottom/top edges are # constant in V; left/right constant in U. bottom = face.uv_coord_of_edge(s2.S2Cell.Boundary.BOTTOM_EDGE) top = face.uv_coord_of_edge(s2.S2Cell.Boundary.TOP_EDGE) self.assertAlmostEqual(bottom, -1.0) self.assertAlmostEqual(top, 1.0) right = face.uv_coord_of_edge(s2.S2Cell.Boundary.RIGHT_EDGE) left = face.uv_coord_of_edge(s2.S2Cell.Boundary.LEFT_EDGE) self.assertAlmostEqual(right, 1.0) self.assertAlmostEqual(left, -1.0) def test_ij_coord_of_edge(self): face = s2.S2Cell.from_face(0) # Face cell in (i,j): bottom/top edges are constant in J (0 and 2^30), # left/right edges are constant in I (0 and 2^30). self.assertEqual(face.ij_coord_of_edge(s2.S2Cell.Boundary.BOTTOM_EDGE), 0) self.assertEqual(face.ij_coord_of_edge(s2.S2Cell.Boundary.TOP_EDGE), 1 << 30) self.assertEqual(face.ij_coord_of_edge(s2.S2Cell.Boundary.LEFT_EDGE), 0) self.assertEqual(face.ij_coord_of_edge(s2.S2Cell.Boundary.RIGHT_EDGE), 1 << 30) def test_center(self): face = s2.S2Cell.from_face(0) c = face.center() # Face 0 center is (1, 0, 0). self.assertAlmostEqual(c.norm(), 1.0) self.assertAlmostEqual(c.x, 1.0, places=5) self.assertAlmostEqual(c.y, 0.0, places=5) self.assertAlmostEqual(c.z, 0.0, places=5) def test_average_area_for_level(self): # AverageArea halves (roughly) with each subdivision by 4: area at # level L is ~ (4*pi / 6) / 4^L. expected_0 = 4.0 * math.pi / 6.0 self.assertAlmostEqual( s2.S2Cell.average_area_for_level(0), expected_0, places=5) # Sum over all cells at level 5 should still be 4*pi. total = s2.S2Cell.average_area_for_level(5) * 6 * (4 ** 5) self.assertAlmostEqual(total, 4.0 * math.pi, places=5) def test_average_area_for_level_out_of_range_raises(self): with self.assertRaises(ValueError): s2.S2Cell.average_area_for_level(31) with self.assertRaises(ValueError): s2.S2Cell.average_area_for_level(-1) def test_approx_area(self): face = s2.S2Cell.from_face(0) expected = 4.0 * math.pi / 6.0 # approx_area is accurate to within 3%. self.assertAlmostEqual(face.approx_area(), expected, delta=expected * 0.03) def test_exact_area_sums_to_sphere(self): # Summing exact_area over all 6 face cells should give 4*pi. total = sum(s2.S2Cell.from_face(f).exact_area() for f in range(6)) self.assertAlmostEqual(total, 4.0 * math.pi, places=10) def test_bound_uv_face(self): face = s2.S2Cell.from_face(0) uv = face.bound_uv() self.assertAlmostEqual(uv.lo.x, -1.0) self.assertAlmostEqual(uv.lo.y, -1.0) self.assertAlmostEqual(uv.hi.x, 1.0) self.assertAlmostEqual(uv.hi.y, 1.0) def test_distance_to_point_outside(self): face = s2.S2Cell.from_face(0) # A point on the opposite face should be at a positive distance. far = s2.S2Point(-1.0, 0.0, 0.0) d = face.distance(far) self.assertGreater(d.radians, 0.0) def test_distance_to_point_inside(self): face = s2.S2Cell.from_face(0) # Center of face 0 is inside; distance should be zero. center = face.center() self.assertAlmostEqual(face.distance(center).radians, 0.0) def test_boundary_distance(self): face = s2.S2Cell.from_face(0) center = face.center() # Interior point has positive boundary distance. self.assertGreater(face.boundary_distance(center).radians, 0.0) # A far exterior point also has positive boundary distance. far = s2.S2Point(-1.0, 0.0, 0.0) self.assertGreater(face.boundary_distance(far).radians, 0.0) def test_max_distance_to_point(self): face = s2.S2Cell.from_face(0) center = face.center() # Max distance from a face cell to its own center should be positive # (distance to the farthest corner). self.assertGreater(face.max_distance(center).radians, 0.0) def test_distance_to_edge(self): face = s2.S2Cell.from_face(0) # An edge on the opposite face; use unit-length endpoints. a = s2.S2Point(-1.0, 1.0, 0.0).normalize() b = s2.S2Point(-1.0, -1.0, 0.0).normalize() self.assertGreater(face.distance_to_edge(a, b).radians, 0.0) def test_max_distance_to_edge(self): face = s2.S2Cell.from_face(0) a = s2.S2Point(-1.0, 1.0, 0.0).normalize() b = s2.S2Point(-1.0, -1.0, 0.0).normalize() self.assertGreater(face.max_distance_to_edge(a, b).radians, 0.0) def test_distance_to_cell(self): face0 = s2.S2Cell.from_face(0) # Distance from a cell to itself is zero. self.assertAlmostEqual(face0.distance_to_cell(face0).radians, 0.0) # Face 0 (pos X) and face 3 (neg X) are opposite and non-adjacent. face3 = s2.S2Cell.from_face(3) self.assertGreater(face0.distance_to_cell(face3).radians, 0.0) def test_max_distance_to_cell(self): face0 = s2.S2Cell.from_face(0) face3 = s2.S2Cell.from_face(3) self.assertGreater(face0.max_distance_to_cell(face3).radians, 0.0) def test_cell_union_bound(self): cell = s2.S2Cell.from_face(0) bound = cell.cell_union_bound() self.assertEqual(len(bound), 1) self.assertEqual(bound[0], cell.id) def test_contains_cell(self): face = s2.S2Cell.from_face(0) child = s2.S2Cell(face.id.child(0)) self.assertTrue(face.contains(child)) self.assertFalse(child.contains(face)) def test_contains_point(self): face = s2.S2Cell.from_face(0) # Face 0 center is (1, 0, 0), which is inside face 0. self.assertTrue(face.contains_point(s2.S2Point(1.0, 0.0, 0.0))) # A point on the opposite face is not in face 0. self.assertFalse(face.contains_point(s2.S2Point(-1.0, 0.0, 0.0))) def test_may_intersect(self): face0 = s2.S2Cell.from_face(0) face1 = s2.S2Cell.from_face(1) # A cell intersects itself. self.assertTrue(face0.may_intersect(face0)) # Distinct faces (disjoint cell id ranges) do not intersect. self.assertFalse(face0.may_intersect(face1)) # A cell contained within another may_intersect the outer cell. child = s2.S2Cell(face0.id.child(0)) self.assertTrue(face0.may_intersect(child)) self.assertTrue(child.may_intersect(face0)) # Traversal def test_subdivide(self): face = s2.S2Cell.from_face(0) children = face.subdivide() self.assertEqual(len(children), 4) for i, child in enumerate(children): self.assertEqual(child.level, 1) self.assertEqual(child.face, 0) # Subdivide should produce the same children as constructing # from the S2CellId children. self.assertEqual(child.id, face.id.child(i)) def test_subdivide_leaf_raises(self): leaf = s2.S2Cell(s2.S2Point(1.0, 0.0, 0.0)) with self.assertRaises(ValueError) as cm: leaf.subdivide() self.assertEqual(str(cm.exception), "Leaf cell has no children") # Operators def test_equality(self): a = s2.S2Cell.from_face(0) b = s2.S2Cell.from_face(0) c = s2.S2Cell.from_face(1) self.assertTrue(a == b) self.assertTrue(a != c) def test_comparison(self): a = s2.S2Cell.from_face(0) b = s2.S2Cell.from_face(1) self.assertTrue(a < b) self.assertTrue(b > a) self.assertTrue(a <= a) self.assertTrue(a >= a) def test_hash(self): a = s2.S2Cell.from_face(0) b = s2.S2Cell.from_face(0) self.assertEqual(hash(a), hash(b)) s = {a, b} self.assertEqual(len(s), 1) # String representation def test_repr(self): cell = s2.S2Cell.from_face(0) self.assertEqual(repr(cell), "S2Cell(0/)") def test_str(self): cell = s2.S2Cell.from_face(0) self.assertEqual(str(cell), "0/") def test_repr_child(self): cell = s2.S2Cell(s2.S2CellId.from_face(3).child(0).child(2)) self.assertEqual(repr(cell), "S2Cell(3/02)") if __name__ == "__main__": unittest.main() src/python/s2geometry_pybind/000077500000000000000000000000001524103652300166345ustar00rootroot00000000000000src/python/s2geometry_pybind/__init__.py000066400000000000000000000001351524103652300207440ustar00rootroot00000000000000"""S2 Geometry library Python bindings using pybind11.""" from s2geometry_bindings import * src/python/s2geometry_test.py000077500000000000000000002253361524103652300167160ustar00rootroot00000000000000# # Copyright 2006 Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS-IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # """Tests for S2 Geometry SWIG bindings.""" from collections import defaultdict import math import unittest import s2geometry as s2 class PyWrapS2TestCase(unittest.TestCase): def testS2PointFromRawToNamedCorrectly(self): x = 1.0 y = 2.0 z = 3.0 point = s2.S2Point_FromRaw(x, y, z) self.assertEqual(x, point.x()) self.assertEqual(y, point.y()) self.assertEqual(z, point.z()) def testContainsIsWrappedCorrectly(self): london = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(51.3368602, 0.4931979), s2.S2LatLng.FromDegrees(51.7323965, 0.1495211), ) e14lj = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(51.5213527, -0.0476026), s2.S2LatLng.FromDegrees(51.5213527, -0.0476026), ) self.assertTrue(london.Contains(e14lj)) def testS2CellIdEqualsIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) cell = s2.S2CellId(london) same_cell = s2.S2CellId(london) self.assertEqual(cell, same_cell) def testS2CellIdComparsionIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) cell = s2.S2CellId(london) self.assertLess(cell, cell.next()) self.assertGreater(cell.next(), cell) def testS2CellIdFromToTokenIsWrappedCorrectly(self): cell = s2.S2CellId.FromToken("487604c489f841c3") self.assertEqual(cell.ToToken(), "487604c489f841c3") self.assertEqual(cell.id(), 0x487604C489F841C3) cell = s2.S2CellId.FromToken("487") self.assertEqual(cell.ToToken(), "487") self.assertEqual(cell.id(), 0x4870000000000000) cell = s2.S2CellId.FromToken("this is invalid") self.assertEqual(cell.ToToken(), "X") self.assertEqual(cell.id(), 0) def testS2CellIdGetEdgeNeighborsIsWrappedCorrectly(self): cell = s2.S2CellId(0x466D319000000000) expected_neighbors = [ s2.S2CellId(0x466D31B000000000), s2.S2CellId(0x466D317000000000), s2.S2CellId(0x466D323000000000), s2.S2CellId(0x466D31F000000000), ] neighbors = cell.GetEdgeNeighbors() self.assertCountEqual(neighbors, expected_neighbors) def testS2CellIdGetVertexNeighborsIsWrappedCorrectly(self): cell = s2.S2CellId(0x466D319000000000) expected_neighbors = [ s2.S2CellId(0x466D31C000000000), s2.S2CellId(0x466D314000000000), s2.S2CellId(0x466D324000000000), s2.S2CellId(0x466D33C000000000), ] self.assertEqual(cell.level(), 12) # Requires level < cell.level. neighbors = cell.GetVertexNeighbors(11) self.assertCountEqual(neighbors, expected_neighbors) def testS2CellIdGetAllNeighborsIsWrappedCorrectly(self): cell = s2.S2CellId(0x466D319000000000) expected_neighbors = [ s2.S2CellId(0x466D31D000000000), s2.S2CellId(0x466D311000000000), s2.S2CellId(0x466D31B000000000), s2.S2CellId(0x466D323000000000), s2.S2CellId(0x466D31F000000000), s2.S2CellId(0x466D317000000000), s2.S2CellId(0x466D321000000000), s2.S2CellId(0x466D33D000000000), ] self.assertEqual(cell.level(), 12) # Requires level >= cell.level. neighbors = cell.GetAllNeighbors(12) self.assertCountEqual(neighbors, expected_neighbors) def testS2CellIdChild(self): valid = s2.S2CellId(0x89C259C000000000) invalid = s2.S2CellId(0) self.assertTrue(valid.is_valid()) self.assertFalse(invalid.is_valid()) self.assertEqual(valid.child(0).parent().id(), valid.id()) with self.assertRaises(ValueError): valid.child(-1) with self.assertRaises(ValueError): valid.child(4) with self.assertRaises(ValueError): invalid.child(0) leaf = s2.S2CellId(s2.S2LatLng.FromDegrees(10.0, 20.0)) with self.assertRaises(ValueError): leaf.child(0) def testS2CellIdChildLevelIsWrappedCorrectly(self): cell = s2.S2CellId(0x876BEC2688E50000) self.assertEqual(cell.child_position(3), 2) with self.assertRaises(ValueError): cell.child_position(-1) with self.assertRaises(ValueError): cell.child_position(0) with self.assertRaises(ValueError): cell.child_position(40) def testS2CellIdContainsInvalidRaises(self): valid = s2.S2CellId(0x89C259C000000000) invalid = s2.S2CellId(0) self.assertTrue(valid.is_valid()) self.assertFalse(invalid.is_valid()) self.assertTrue(valid.contains(valid)) with self.assertRaises(ValueError): valid.contains(invalid) with self.assertRaises(ValueError): invalid.contains(valid) def testS2CellIdGetAllNeighborsIsWrappedCorrectly(self): cell = s2.S2CellId(0x6AA7590000000000) expected_neighbors = ( s2.S2CellId(0x2AB3530000000000), s2.S2CellId(0x2AB34B0000000000), s2.S2CellId(0x2AB34D0000000000), s2.S2CellId(0x6AA75B0000000000), s2.S2CellId(0x6AA7570000000000), s2.S2CellId(0x6AA75F0000000000), s2.S2CellId(0x6AA7510000000000), s2.S2CellId(0x6AA75D0000000000), ) neighbors = cell.GetAllNeighbors(cell.level()) self.assertEqual(neighbors, expected_neighbors) def testS2CellIdIntersectsIsTrueForOverlap(self): cell1 = s2.S2CellId(0x89C259C000000000) cell2 = s2.S2CellId(0x89C2590000000000) self.assertTrue(cell1.intersects(cell2)) def testS2CellIdIntersectsIsFalseForNonOverlap(self): cell1 = s2.S2CellId(0x89C259C000000000) cell2 = s2.S2CellId(0x89E83D0000000000) self.assertFalse(cell1.intersects(cell2)) def testS2CellIdIntersectsInvalidRaises(self): valid = s2.S2CellId(0x89C259C000000000) invalid = s2.S2CellId(0) self.assertTrue(valid.is_valid()) self.assertFalse(invalid.is_valid()) with self.assertRaises(ValueError): valid.intersects(invalid) with self.assertRaises(ValueError): invalid.intersects(valid) def testS2CellIdLevel(self): leaf = s2.S2CellId(s2.S2LatLng.FromDegrees(10.0, 20.0)) self.assertEqual(leaf.level(), 30) with self.assertRaises(ValueError): s2.S2CellId(0).level() def testS2CellIdParent(self): leaf = s2.S2CellId(s2.S2LatLng.FromDegrees(10.0, 20.0)) self.assertEqual(leaf.level(), 30) self.assertEqual(leaf.parent().level(), 29) level8 = leaf.parent(8) self.assertEqual(level8.level(), 8) self.assertEqual(level8.parent(0).level(), 0) # Error to have negative level. with self.assertRaises(ValueError): level8.parent(-1) # Same level is ok. self.assertEqual(level8.parent(8).level(), 8) # Error to ask for parent with lower level. with self.assertRaises(ValueError): level8.parent(9) # Parent of invalid is an error with self.assertRaises(ValueError): s2.S2CellId(0).parent() def testS2HashingIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) cell = s2.S2CellId(london) same_cell = s2.S2CellId(london) self.assertEqual(hash(cell), hash(same_cell)) def testCovererIsWrappedCorrectly(self): london = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(51.3368602, 0.4931979), s2.S2LatLng.FromDegrees(51.7323965, 0.1495211), ) e14lj = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(51.5213527, -0.0476026), s2.S2LatLng.FromDegrees(51.5213527, -0.0476026), ) coverer = s2.S2RegionCoverer() coverer.set_max_cells(6) self.assertEqual(6, coverer.max_cells()) covering = coverer.GetCovering(e14lj) self.assertLessEqual(len(covering), 6) for cellid in covering: self.assertTrue(london.Contains(s2.S2Cell(cellid))) interior = coverer.GetInteriorCovering(e14lj) for cellid in interior: self.assertTrue(london.Contains(s2.S2Cell(cellid))) def testS2CellUnionIsWrappedCorrectly(self): cell_union = s2.S2CellUnion() cell_union.Init([0x466D319000000000, 0x466D31B000000000]) self.assertEqual(cell_union.num_cells(), 2) trondheim = s2.S2LatLng.FromDegrees(63.431052, 10.395083) self.assertTrue(cell_union.Contains(s2.S2CellId(trondheim))) # Init() calls Normalized, so cell_ids() are normalized. cell_union2 = s2.S2CellUnion.FromNormalized(cell_union.cell_ids()) # There is no S2CellUnion::Equals, and cell_ids is a non-iterable # SWIG object, so just perform the same checks again. self.assertEqual(cell_union2.num_cells(), 2) self.assertTrue(cell_union2.Contains(s2.S2CellId(trondheim))) def testS2PolygonIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon = s2.S2Polygon(s2.S2Cell(s2.S2CellId(london))) self.assertEqual(polygon.num_loops(), 1) point = london.ToPoint() self.assertTrue(polygon.Contains(point)) def testS2LoopIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon = s2.S2Polygon(s2.S2Cell(s2.S2CellId(london))) loop = polygon.loop(0) self.assertTrue(loop.IsValid()) self.assertEqual(0, loop.depth()) self.assertFalse(loop.is_hole()) self.assertEqual(4, loop.num_vertices()) self.assertTrue(loop.IsNormalized()) point = london.ToPoint() self.assertTrue(loop.Contains(point)) def testS2LoopUsesValueEquality(self): self.assertEqual(s2.S2Loop(), s2.S2Loop()) def testS2PolygonCopiesLoopInConstructorBecauseItTakesOwnership(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) loop = s2.S2Loop(s2.S2Cell(s2.S2CellId(london))) s2.S2Polygon(loop) def testS2LoopAreaIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) loop = s2.S2Loop(s2.S2Cell(s2.S2CellId(london))) equivalent_polygon = s2.S2Polygon(loop) self.assertAlmostEqual(loop.GetArea(), equivalent_polygon.GetArea()) def testS2PolygonInitNestedIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) small_loop = s2.S2Loop(s2.S2Cell(s2.S2CellId(london))) big_loop = s2.S2Loop(s2.S2Cell(s2.S2CellId(london).parent(1))) polygon = s2.S2Polygon() polygon.InitNested([big_loop, small_loop]) def testS2PolygonInitNestedWithIncorrectTypeIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) loop = s2.S2Loop(s2.S2Cell(s2.S2CellId(london))) polygon = s2.S2Polygon() with self.assertRaises(TypeError): polygon.InitNested([loop, s2.S2CellId()]) def testS2PolygonGetAreaIsWrappedCorrectly(self): # Cell at level 10 containing central London. london_level_10 = s2.S2CellId( s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) ).parent(10) polygon = s2.S2Polygon(s2.S2Cell(london_level_10)) # Because S2Cell.ExactArea() isn't swigged, compare S2Polygon.GetArea() with # S2CellUnion.ExactArea(). cell_union = s2.S2CellUnion() cell_union.Init([london_level_10.id()]) self.assertAlmostEqual( cell_union.ExactArea(), polygon.GetArea(), places=10 ) def testS2PolygonGetOverlapFractions(self): # Matches S2Polygon, OverlapFractions test from cs/s2polygon_test.cc a = s2.S2Polygon() b = s2.S2Polygon() r1, r2 = s2.S2Polygon.GetOverlapFractions(a, b) self.assertAlmostEqual(1.0, r1) self.assertAlmostEqual(1.0, r2) def verts2loop(vs): loop = s2.S2Loop() loop.Init([s2.S2LatLng.FromDegrees(*v).ToPoint() for v in vs]) return loop loop1verts = [(-10, 10), (0, 10), (0, -10), (-10, -10), (-10, 0)] b = s2.S2Polygon(verts2loop(loop1verts)) r1, r2 = s2.S2Polygon.GetOverlapFractions(a, b) self.assertAlmostEqual(1.0, r1) self.assertAlmostEqual(0.0, r2) loop2verts = [(-10, 0), (10, 0), (10, -10), (-10, -10)] a = s2.S2Polygon(verts2loop(loop2verts)) r1, r2 = s2.S2Polygon.GetOverlapFractions(a, b) self.assertAlmostEqual(0.5, r1) self.assertAlmostEqual(0.5, r2) def testGetS2LatLngVertexIsWrappedCorrectly(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon = s2.S2Polygon(s2.S2Cell(s2.S2CellId(london))) loop = polygon.loop(0) first_vertex = loop.GetS2LatLngVertex(0) self.assertIsInstance(first_vertex, s2.S2LatLng) self.assertEqual( "51.500152,-0.126235", first_vertex.ToStringInDegrees() ) second_vertex = loop.GetS2LatLngVertex(1) self.assertIsInstance(second_vertex, s2.S2LatLng) self.assertEqual( "51.500153,-0.126235", second_vertex.ToStringInDegrees() ) def testGetLastDescendant(self): def verts2loop(vs): loop = s2.S2Loop() loop.Init([s2.S2LatLng.FromDegrees(*v).ToPoint() for v in vs]) return loop loop1 = verts2loop([(0, 0), (0, 10), (10, 10), (10, 0)]) # Shell loop2 = verts2loop([(2, 2), (2, 5), (5, 5), (5, 2)]) # Hole loop3 = verts2loop([(0, 20), (0, 30), (10, 30), (10, 20)]) # Shell polygon = s2.S2Polygon() polygon.InitNested([loop1, loop2, loop3]) self.assertEqual(1, polygon.GetLastDescendant(0)) self.assertEqual(1, polygon.GetLastDescendant(1)) self.assertEqual(2, polygon.GetLastDescendant(2)) def testS2PolylineInitFromS2LatLngs(self): e7_10deg = 0x5F5E100 list_ll = [] for lat, lng in [(0, 0), (0, e7_10deg), (e7_10deg, e7_10deg)]: list_ll.append(s2.S2LatLng.FromE7(lat, lng)) line = s2.S2Polyline() line.InitFromS2LatLngs(list_ll) self.assertAlmostEqual(20.0, line.GetLength().degrees()) def testS2PolylineInitFromS2Points(self): e7_10deg = 0x5F5E100 list_points = [] for lat, lng in [(0, 0), (0, e7_10deg), (e7_10deg, e7_10deg)]: list_points.append(s2.S2LatLng.FromE7(lat, lng).ToPoint()) line = s2.S2Polyline() line.InitFromS2Points(list_points) self.assertAlmostEqual(20.0, line.GetLength().degrees()) def testS2PolylineUsesValueEquality(self): self.assertEqual(s2.S2Polyline(), s2.S2Polyline()) def testS2PointsCanBeNormalized(self): line = s2.S2Polyline() line.InitFromS2LatLngs([ s2.S2LatLng.FromDegrees(37.794484, -122.394871), s2.S2LatLng.FromDegrees(37.762699, -122.435158), ]) self.assertNotAlmostEqual(line.GetCentroid().Norm(), 1.0) self.assertAlmostEqual(line.GetCentroid().Normalize().Norm(), 1.0) def testS1AngleComparsionIsWrappedCorrectly(self): ten_degrees = s2.S1Angle.Degrees(10) one_hundred_degrees = s2.S1Angle.Degrees(100) self.assertLess(ten_degrees, one_hundred_degrees) self.assertGreater(one_hundred_degrees, ten_degrees) def testS2PolygonIntersectsWithPolyline(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon = s2.S2Polygon(s2.S2Cell(s2.S2CellId(london).parent(15))) line = s2.S2Polyline() line.InitFromS2LatLngs([ s2.S2LatLng.FromDegrees(51.5, -0.128), s2.S2LatLng.FromDegrees(51.5, -0.125), ]) intersections = polygon.IntersectWithPolyline(line) self.assertEqual(1, len(intersections)) def testS2PolygonBoundaryNearIsSame(self): london_1 = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon_1 = s2.S2Polygon(s2.S2Loop(s2.S2Cell(s2.S2CellId(london_1)))) london_2 = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon_2 = s2.S2Polygon(s2.S2Loop(s2.S2Cell(s2.S2CellId(london_2)))) self.assertTrue(polygon_1.BoundaryNear(polygon_2)) def testS2PolygonBoundaryNearIsTotallyDifferent(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon_1 = s2.S2Polygon(s2.S2Loop(s2.S2Cell(s2.S2CellId(london)))) seattle = s2.S2LatLng.FromDegrees(47.6062, -122.3321) polygon_2 = s2.S2Polygon(s2.S2Loop(s2.S2Cell(s2.S2CellId(seattle)))) self.assertFalse(polygon_1.BoundaryNear(polygon_2)) def testS2PolygonBoundaryNearIsNear(self): def verts2loop(vs): loop = s2.S2Loop() loop.Init([s2.S2LatLng.FromDegrees(*v).ToPoint() for v in vs]) return loop vertices_1 = [(-10, 10), (0, 10), (0, -10), (-10, -10), (-10, 0)] polygon_1 = s2.S2Polygon(verts2loop(vertices_1)) vertices_2 = [(-10, 10), (0, 10), (0, -10.1), (-10, -10), (-10, 0)] polygon_2 = s2.S2Polygon(verts2loop(vertices_2)) self.assertTrue( polygon_1.BoundaryNear(polygon_2, s2.S1Angle.Degrees(1)) ) def testS2PolygonUsesValueEquality(self): self.assertEqual(s2.S2Polygon(), s2.S2Polygon()) def testCrossingSign(self): a = s2.S2LatLng.FromDegrees(-1, 0).ToPoint() b = s2.S2LatLng.FromDegrees(1, 0).ToPoint() c = s2.S2LatLng.FromDegrees(0, -1).ToPoint() d = s2.S2LatLng.FromDegrees(0, 1).ToPoint() # SWIG flattens namespaces, so this is just s2.CrossingSign, # not s2.S2.CrossingSign. self.assertEqual(1, s2.CrossingSign(a, b, c, d)) def testGetIntersection(self): a = s2.S2LatLng.FromDegrees(-1, 0).ToPoint() b = s2.S2LatLng.FromDegrees(1, 0).ToPoint() c = s2.S2LatLng.FromDegrees(0, -1).ToPoint() d = s2.S2LatLng.FromDegrees(0, 1).ToPoint() # SWIG namespace flattening as above. intersection = s2.GetIntersection(a, b, c, d) self.assertEqual( "0.000000,0.000000", s2.S2LatLng(intersection).ToStringInDegrees() ) def testS2CellDistance(self): # Level-0 cell (i.e. face) centered at (0, 0) cell = s2.S2Cell(s2.S2CellId(0x1000000000000000)) p1 = s2.S2LatLng.FromDegrees(0, 0).ToPoint() self.assertTrue(cell.Contains(p1)) d1 = cell.GetDistance(p1).ToAngle().degrees() # Inside, so distance is 0, but boundary distance is not. self.assertEqual(0.0, d1) bd1 = cell.GetBoundaryDistance(p1).ToAngle().degrees() self.assertEqual(45.0, bd1) p2 = s2.S2LatLng.FromDegrees(0, 90).ToPoint() self.assertFalse(cell.Contains(p2)) d2 = cell.GetDistance(p2).ToAngle().degrees() self.assertAlmostEqual(45.0, d2) bd2 = cell.GetBoundaryDistance(p2).ToAngle().degrees() # Outside, so distance and boundary distance are the same. self.assertAlmostEqual(45.0, bd2) def testS2Rotate(self): mtv_a = s2.S2LatLng.FromDegrees(37.4402777, -121.9638888).ToPoint() mtv_b = s2.S2LatLng.FromDegrees(37.3613888, -121.9283333).ToPoint() angle = s2.S1Angle.Radians(0.039678) point = s2.Rotate(mtv_a, mtv_b, angle) self.assertEqual( "37.439095,-121.967802", s2.S2LatLng(point).ToStringInDegrees() ) def testS2TurnAngle(self): mtv_a = s2.S2LatLng.FromDegrees(37.4402777, -121.9638888).ToPoint() mtv_b = s2.S2LatLng.FromDegrees(37.3613888, -121.9283333).ToPoint() mtv_c = s2.S2LatLng.FromDegrees(37.3447222, -122.0308333).ToPoint() angle = s2.TurnAngle(mtv_a, mtv_b, mtv_c) self.assertAlmostEqual(-1.7132025, angle) def testEncodeDecode(self): london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) polygon = s2.S2Polygon(s2.S2Cell(s2.S2CellId(london).parent(15))) self.assertEqual(polygon.num_loops(), 1) encoder = s2.Encoder() polygon.Encode(encoder) encoded = encoder.buffer() decoder = s2.Decoder(encoded) decoded_polygon = s2.S2Polygon() self.assertTrue(decoded_polygon.Decode(decoder)) self.assertEqual(decoded_polygon.num_loops(), 1) self.assertTrue(decoded_polygon.Equals(polygon)) def testS2CapRegion(self): center = s2.S2LatLng.FromDegrees(2.0, 3.0).ToPoint() cap = s2.S2Cap(center, s2.S1Angle.Degrees(1.0)) inside = s2.S2LatLng.FromDegrees(2.1, 2.9).ToPoint() outside = s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint() self.assertTrue(cap.Contains(inside)) self.assertFalse(cap.Contains(outside)) self.assertTrue(cap.Contains(s2.S2Cell(inside))) self.assertFalse(cap.Contains(s2.S2Cell(outside))) self.assertTrue(cap.MayIntersect(s2.S2Cell(inside))) self.assertFalse(cap.MayIntersect(s2.S2Cell(outside))) self.assertTrue(cap.ApproxEquals(cap.GetCapBound())) rect_bound = cap.GetRectBound() self.assertTrue(rect_bound.Contains(inside)) self.assertFalse(rect_bound.Contains(outside)) def testS2LatLngRectRegion(self): rect = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(1.0, 2.0), s2.S2LatLng.FromDegrees(3.0, 4.0) ) inside = s2.S2LatLng.FromDegrees(2.0, 3.0).ToPoint() outside = s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint() self.assertTrue(rect.Contains(inside)) self.assertFalse(rect.Contains(outside)) self.assertTrue(rect.Contains(s2.S2Cell(inside))) self.assertFalse(rect.Contains(s2.S2Cell(outside))) self.assertTrue(rect.MayIntersect(s2.S2Cell(inside))) self.assertFalse(rect.MayIntersect(s2.S2Cell(outside))) cap_bound = rect.GetCapBound() self.assertTrue(cap_bound.Contains(inside)) self.assertFalse(cap_bound.Contains(outside)) self.assertTrue(rect.ApproxEquals(rect.GetRectBound())) def testS2CellRegion(self): cell = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) inside = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() outside = s2.S2LatLng.FromDegrees(30.0, 40.0).ToPoint() self.assertTrue(cell.Contains(inside)) self.assertFalse(cell.Contains(outside)) self.assertTrue(cell.Contains(s2.S2Cell(inside))) self.assertFalse(cell.Contains(s2.S2Cell(outside))) self.assertTrue(cell.MayIntersect(s2.S2Cell(inside))) self.assertFalse(cell.MayIntersect(s2.S2Cell(outside))) cap_bound = cell.GetCapBound() self.assertTrue(cap_bound.Contains(inside)) self.assertFalse(cap_bound.Contains(outside)) rect_bound = cell.GetRectBound() self.assertTrue(rect_bound.Contains(inside)) self.assertFalse(rect_bound.Contains(outside)) def testS2CellUnionRegion(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) cell_union = s2.S2CellUnion() cell_union.Init([cell_id.id()]) inside = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() outside = s2.S2LatLng.FromDegrees(30.0, 40.0).ToPoint() self.assertTrue(cell_union.Contains(inside)) self.assertFalse(cell_union.Contains(outside)) self.assertTrue(cell_union.Contains(s2.S2Cell(inside))) self.assertFalse(cell_union.Contains(s2.S2Cell(outside))) self.assertTrue(cell_union.MayIntersect(s2.S2Cell(inside))) self.assertFalse(cell_union.MayIntersect(s2.S2Cell(outside))) cap_bound = cell_union.GetCapBound() self.assertTrue(cap_bound.Contains(inside)) self.assertFalse(cap_bound.Contains(outside)) rect_bound = cell_union.GetRectBound() self.assertTrue(rect_bound.Contains(inside)) self.assertFalse(rect_bound.Contains(outside)) def testS2CellUnionEmpty(self): empty_cell_union = s2.S2CellUnion() self.assertTrue(empty_cell_union.empty()) cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) cell_union = s2.S2CellUnion() cell_union.Init([cell_id.id()]) self.assertFalse(cell_union.empty()) def testS2CellUnionIntersectionWithS2CellUnion(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)) cell_union = s2.S2CellUnion() cell_union.Init([cell_id.id()]) # No intersection. outside_cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(5.0, 6.0)) outside_cell_union = s2.S2CellUnion() outside_cell_union.Init([outside_cell_id.id()]) empty_intersection = cell_union.Intersection(outside_cell_union) self.assertTrue(empty_intersection.empty()) # Complete overlap. self_intersection = cell_union.Intersection(cell_union) self.assertTrue(self_intersection.Contains(cell_union)) self.assertTrue(cell_union.Contains(self_intersection)) # Some intersection. joint_cell_union = s2.S2CellUnion() joint_cell_union.Init([cell_id.id(), outside_cell_id.id()]) outside_intersection = joint_cell_union.Intersection(outside_cell_union) self.assertTrue(outside_intersection.Contains(outside_cell_id)) self.assertFalse(outside_intersection.Contains(cell_id)) def testS2CellUnionIntersectionWithS2CellId(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)) cell_union = s2.S2CellUnion() cell_union.Init([cell_id.id()]) # No intersection. outside_cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(4.0, 5.0)) empty_intersection = cell_union.Intersection(outside_cell_id) self.assertTrue(empty_intersection.empty()) # Complete overlap. intersection = cell_union.Intersection(cell_id) self.assertTrue(intersection.Contains(cell_id)) # Some intersection. joint_cell_union = s2.S2CellUnion() joint_cell_union.Init([cell_id.id(), outside_cell_id.id()]) outside_intersection = joint_cell_union.Intersection(outside_cell_id) self.assertTrue(outside_intersection.Contains(outside_cell_id)) self.assertFalse(outside_intersection.Contains(cell_id)) def testS2CellUnionIsNormalized(self): empty_cell_union = s2.S2CellUnion() self.assertTrue(empty_cell_union.IsNormalized()) london = s2.S2LatLng.FromDegrees(51.5001525, -0.1262355) london_cell_id = s2.S2CellId(london) normalized_union = s2.S2CellUnion() normalized_union.Init([london_cell_id.id()]) self.assertTrue(normalized_union.IsNormalized()) def testS2CellUnionNormalizeS2CellUnion(self): empty_cell_union = s2.S2CellUnion() empty_cell_union.NormalizeS2CellUnion() self.assertTrue(empty_cell_union.IsNormalized()) cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) cell_union = s2.S2CellUnion() cell_union.Init([cell_id.id()]) cell_union.NormalizeS2CellUnion() self.assertTrue(cell_union.IsNormalized()) def testS2LoopRegion(self): cell = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) loop = s2.S2Loop(cell) inside = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() outside = s2.S2LatLng.FromDegrees(30.0, 40.0).ToPoint() self.assertTrue(loop.Contains(inside)) self.assertFalse(loop.Contains(outside)) self.assertTrue(loop.Contains(s2.S2Cell(inside))) self.assertFalse(loop.Contains(s2.S2Cell(outside))) self.assertTrue(loop.MayIntersect(s2.S2Cell(inside))) self.assertFalse(loop.MayIntersect(s2.S2Cell(outside))) cap_bound = loop.GetCapBound() self.assertTrue(cap_bound.Contains(inside)) self.assertFalse(cap_bound.Contains(outside)) rect_bound = loop.GetRectBound() self.assertTrue(rect_bound.Contains(inside)) self.assertFalse(rect_bound.Contains(outside)) def testS2PolygonRegion(self): cell = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) polygon = s2.S2Polygon(cell) inside = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() outside = s2.S2LatLng.FromDegrees(30.0, 40.0).ToPoint() self.assertTrue(polygon.Contains(inside)) self.assertFalse(polygon.Contains(outside)) self.assertTrue(polygon.Contains(s2.S2Cell(inside))) self.assertFalse(polygon.Contains(s2.S2Cell(outside))) self.assertTrue(polygon.MayIntersect(s2.S2Cell(inside))) self.assertFalse(polygon.MayIntersect(s2.S2Cell(outside))) cap_bound = polygon.GetCapBound() self.assertTrue(cap_bound.Contains(inside)) self.assertFalse(cap_bound.Contains(outside)) rect_bound = polygon.GetRectBound() self.assertTrue(rect_bound.Contains(inside)) self.assertFalse(rect_bound.Contains(outside)) def testS2PolylineRegion(self): polyline = s2.S2Polyline() polyline.InitFromS2LatLngs([ s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(1.0, 1.0), ]) # Contains(S2Point) always return false. self.assertFalse( polyline.Contains(s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint()) ) self.assertFalse( polyline.Contains(s2.S2Cell(s2.S2LatLng.FromDegrees(0.0, 0.0))) ) self.assertTrue( polyline.MayIntersect(s2.S2Cell(s2.S2LatLng.FromDegrees(0.0, 0.0))) ) self.assertFalse( polyline.MayIntersect(s2.S2Cell(s2.S2LatLng.FromDegrees(3.0, 4.0))) ) cap_bound = polyline.GetCapBound() self.assertTrue( cap_bound.Contains(s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint()) ) self.assertFalse( cap_bound.Contains(s2.S2LatLng.FromDegrees(2.0, 2.0).ToPoint()) ) rect_bound = polyline.GetRectBound() self.assertTrue( rect_bound.Contains(s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint()) ) self.assertFalse( rect_bound.Contains(s2.S2LatLng.FromDegrees(2.0, 2.0).ToPoint()) ) def testS2CellIdCenterSiTi(self): cell = s2.S2CellId.FromFacePosLevel( 3, 0x12345678, s2.S2CellId.kMaxLevel ) # Check that the (si, ti) coordinates of the center end in a # 1 followed by (30 - level) 0s. # Leaf level, 30. face, si, ti = cell.GetCenterSiTi() self.assertEqual(3, face) self.assertEqual(1 << 0, si & 1) self.assertEqual(1 << 0, ti & 1) # Level 29. face, si, ti = cell.parent(s2.S2CellId.kMaxLevel - 1).GetCenterSiTi() self.assertEqual(3, face) self.assertEqual(1 << 1, si & 3) self.assertEqual(1 << 1, ti & 3) # Level 28. face, si, ti = cell.parent(s2.S2CellId.kMaxLevel - 2).GetCenterSiTi() self.assertEqual(3, face) self.assertEqual(1 << 2, si & 7) self.assertEqual(1 << 2, ti & 7) # Level 20. face, si, ti = cell.parent(s2.S2CellId.kMaxLevel - 10).GetCenterSiTi() self.assertEqual(3, face) self.assertEqual(1 << 10, si & ((1 << 11) - 1)) self.assertEqual(1 << 10, ti & ((1 << 11) - 1)) # Level 10. face, si, ti = cell.parent(s2.S2CellId.kMaxLevel - 20).GetCenterSiTi() self.assertEqual(3, face) self.assertEqual(1 << 20, si & ((1 << 21) - 1)) self.assertEqual(1 << 20, ti & ((1 << 21) - 1)) # Level 0. face, si, ti = cell.parent(0).GetCenterSiTi() self.assertEqual(3, face) self.assertEqual(1 << 30, si & ((1 << 31) - 1)) self.assertEqual(1 << 30, ti & ((1 << 31) - 1)) def testS2CellIdToFromFaceIJ(self): cell = s2.S2CellId.FromFaceIJ(3, 1234, 5678) face, i, j, _ = cell.ToFaceIJOrientation() self.assertEqual(3, face) self.assertEqual(1234, i) self.assertEqual(5678, j) def testS2EarthMetricRadians(self): radius_rad = s2.S2Earth.KmToRadians(12.34) self.assertAlmostEqual(radius_rad, 0.0019368985451286374) angle = s2.S1Angle.Radians(radius_rad) radius_m = s2.S2Earth.RadiansToMeters(angle.radians()) self.assertEqual(radius_m, 12340.0) def testS2Point_ToFromRaw(self): p = s2.S2Point_FromRaw(1.0, 1.0, 1.0) p = p.Normalize() p_raw = s2.S2Point_ToRaw(p) self.assertAlmostEqual(p_raw[0], 0.57735027) self.assertAlmostEqual(p_raw[1], 0.57735027) self.assertAlmostEqual(p_raw[2], 0.57735027) def testS2Interpolate(self): p1 = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() p2 = s2.S2LatLng.FromDegrees(4.0, 5.0).ToPoint() p3 = s2.Interpolate(p1, p2, 0.5) self.assertEqual( "3.500133,4.499733", s2.S2LatLng(p3).ToStringInDegrees() ) def testS2predOrderedCCW(self): pC = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() p1 = s2.S2LatLng.FromDegrees(3.0, 5.0).ToPoint() p2 = s2.S2LatLng.FromDegrees(2.7, 3.0).ToPoint() p3 = s2.S2LatLng.FromDegrees(3.3, 3.0).ToPoint() self.assertFalse(s2.OrderedCCW(p1, p2, p3, pC)) self.assertTrue(s2.OrderedCCW(p2, p1, p3, pC)) self.assertTrue(s2.OrderedCCW(p1, p3, p2, pC)) self.assertTrue(s2.OrderedCCW(p3, p2, p1, pC)) def testS2UpdateMinDistance(self): pC = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() p1 = s2.S2LatLng.FromDegrees(3.0, 5.0).ToPoint() p2 = s2.S2LatLng.FromDegrees(2.7, 3.0).ToPoint() md = s2.S1ChordAngle.Infinity() self.assertTrue(s2.UpdateMinDistance(pC, p1, p2, md)) self.assertAlmostEqual(0.1478883, md.degrees()) pC = s2.S2LatLng.FromDegrees(3.0, 40.0).ToPoint() self.assertFalse(s2.UpdateMinDistance(pC, p1, p2, md)) self.assertAlmostEqual(0.1478883, md.degrees()) def testS1AngleToString(self): a = s2.S1Angle.Degrees(123) self.assertEqual("123.0000000", str(a)) def testS2CellIdToString(self): a = s2.S2CellId(12345) self.assertEqual("0/000000000000000000000001200130", str(a)) class S1AngleTest(unittest.TestCase): def testE5(self): a = s2.S1Angle.E5(1000000) self.assertAlmostEqual(10.0, a.degrees()) def testE6(self): a = s2.S1Angle.E6(10000000) self.assertAlmostEqual(10.0, a.degrees()) def testE7(self): a = s2.S1Angle.E7(100000000) self.assertAlmostEqual(10.0, a.degrees()) def testAccessors_e6_e7(self): a = s2.S1Angle.Degrees(45.0) self.assertEqual(45000000, a.e6()) self.assertEqual(450000000, a.e7()) def testUnsignedE6(self): a = s2.S1Angle.UnsignedE6(10000000) self.assertAlmostEqual(10.0, a.degrees()) def testNormalize(self): a = s2.S1Angle.Degrees(360 + 45) a.Normalize() self.assertAlmostEqual(45.0, a.degrees()) def testNormalized(self): a = s2.S1Angle.Degrees(360 + 45) b = a.Normalized() self.assertAlmostEqual(45.0, b.degrees()) def testAbs(self): a = s2.S1Angle.Degrees(-45.0) b = a.abs() self.assertAlmostEqual(45.0, b.degrees()) def testRadiansAccessor(self): a = s2.S1Angle.Degrees(180.0) self.assertAlmostEqual(3.14159265, a.radians(), places=5) class S2CapTest(unittest.TestCase): def testEmpty(self): cap = s2.S2Cap.Empty() self.assertTrue(cap.is_empty()) def testFull(self): cap = s2.S2Cap.Full() self.assertTrue(cap.is_valid()) self.assertFalse(cap.is_empty()) def testFromPoint(self): p = s2.S2LatLng.FromDegrees(1.0, 2.0).ToPoint() cap = s2.S2Cap.FromPoint(p) self.assertTrue(cap.is_valid()) self.assertTrue(cap.Contains(p)) def testFromCenterHeight(self): p = s2.S2LatLng.FromDegrees(1.0, 2.0).ToPoint() cap = s2.S2Cap.FromCenterHeight(p, 0.5) self.assertTrue(cap.is_valid()) self.assertAlmostEqual(0.5, cap.height()) def testCenterAndHeight(self): center = s2.S2LatLng.FromDegrees(2.0, 3.0).ToPoint() cap = s2.S2Cap(center, s2.S1Angle.Degrees(1.0)) c = cap.center() self.assertIsInstance(c, s2.S2Point) self.assertGreater(cap.height(), 0.0) def testGetCentroid(self): center = s2.S2LatLng.FromDegrees(2.0, 3.0).ToPoint() cap = s2.S2Cap(center, s2.S1Angle.Degrees(1.0)) centroid = cap.GetCentroid() self.assertIsInstance(centroid, s2.S2Point) def testExpanded(self): center = s2.S2LatLng.FromDegrees(2.0, 3.0).ToPoint() cap = s2.S2Cap(center, s2.S1Angle.Degrees(1.0)) expanded = cap.Expanded(s2.S1Angle.Degrees(1.0)) self.assertGreater(expanded.height(), cap.height()) def testUnion(self): p1 = s2.S2LatLng.FromDegrees(1.0, 1.0).ToPoint() p2 = s2.S2LatLng.FromDegrees(10.0, 10.0).ToPoint() cap1 = s2.S2Cap(p1, s2.S1Angle.Degrees(1.0)) cap2 = s2.S2Cap(p2, s2.S1Angle.Degrees(1.0)) union = cap1.Union(cap2) self.assertTrue(union.Contains(p1)) self.assertTrue(union.Contains(p2)) def testIntersects(self): p1 = s2.S2LatLng.FromDegrees(1.0, 1.0).ToPoint() cap1 = s2.S2Cap(p1, s2.S1Angle.Degrees(5.0)) cap2 = s2.S2Cap(p1, s2.S1Angle.Degrees(1.0)) self.assertTrue(cap1.Intersects(cap2)) def testEncodeDecode(self): center = s2.S2LatLng.FromDegrees(2.0, 3.0).ToPoint() cap = s2.S2Cap(center, s2.S1Angle.Degrees(1.0)) encoder = s2.Encoder() cap.Encode(encoder) decoder = s2.Decoder(encoder.buffer()) cap2 = s2.S2Cap() self.assertTrue(cap2.Decode(decoder)) # S2Cap.ApproxEquals is not exposed via SWIG, so compare heights. self.assertAlmostEqual(cap.height(), cap2.height()) def testAddPoint(self): cap = s2.S2Cap.Empty() p = s2.S2LatLng.FromDegrees(1.0, 2.0).ToPoint() cap.AddPoint(p) self.assertTrue(cap.Contains(p)) class S2CellTest(unittest.TestCase): def testApproxArea(self): cell = s2.S2Cell(s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10)) self.assertGreater(cell.ApproxArea(), 0.0) def testExactArea(self): cell = s2.S2Cell(s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10)) self.assertGreater(cell.ExactArea(), 0.0) def testAverageArea(self): area = s2.S2Cell.AverageArea(10) self.assertGreater(area, 0.0) def testGetCenter(self): cell = s2.S2Cell(s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10)) center = cell.GetCenter() self.assertIsInstance(center, s2.S2Point) def testGetVertex(self): cell = s2.S2Cell(s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10)) v = cell.GetVertex(0) self.assertIsInstance(v, s2.S2Point) def testGetS2LatLngEdge(self): cell = s2.S2Cell(s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10)) edge = cell.GetS2LatLngEdge(0) self.assertIsInstance(edge, s2.S2LatLng) def testFaceAndLevel(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10) cell = s2.S2Cell(cell_id) self.assertEqual(10, cell.level()) self.assertIn(cell.face(), range(6)) def testIdRoundTrip(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10) cell = s2.S2Cell(cell_id) self.assertEqual(cell_id, cell.id()) def testEncodeDecode(self): cell = s2.S2Cell(s2.S2CellId(s2.S2LatLng.FromDegrees(0, 0)).parent(10)) encoder = s2.Encoder() cell.Encode(encoder) decoder = s2.Decoder(encoder.buffer()) cell2 = s2.S2Cell() self.assertTrue(cell2.Decode(decoder)) self.assertEqual(cell.id(), cell2.id()) class S2CellIdTest(unittest.TestCase): def testBeginEnd(self): begin = s2.S2CellId.Begin(0) end = s2.S2CellId.End(0) self.assertTrue(begin.is_valid()) self.assertLess(begin, end) def testChildBeginEnd(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) begin = cell_id.child_begin() end = cell_id.child_end() self.assertLess(begin, end) def testIsLeaf(self): leaf = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)) self.assertTrue(leaf.is_leaf()) non_leaf = leaf.parent(10) self.assertFalse(non_leaf.is_leaf()) def testIsFace(self): face = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(0) self.assertTrue(face.is_face()) non_face = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) self.assertFalse(non_face.is_face()) def testPos(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)) pos = cell_id.pos() self.assertIsInstance(pos, int) def testRangeMinMax(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) rmin = cell_id.range_min() rmax = cell_id.range_max() self.assertLess(rmin, rmax) def testNextPrev(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) nxt = cell_id.next() prv = cell_id.prev() self.assertNotEqual(cell_id, nxt) self.assertNotEqual(cell_id, prv) self.assertEqual(cell_id, nxt.prev()) self.assertEqual(cell_id, prv.next()) def testKMaxLevel(self): self.assertEqual(30, s2.S2CellId.kMaxLevel) class S2CellUnionTest(unittest.TestCase): def testApproxArea(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) cu = s2.S2CellUnion() cu.Init([cell_id.id()]) self.assertGreater(cu.ApproxArea(), 0.0) def testDenormalize(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) cu = s2.S2CellUnion() cu.Init([cell_id.id()]) denormed = cu.Denormalize(0, 1) self.assertGreater(len(denormed), 0) def testCellId(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) cu = s2.S2CellUnion() cu.Init([cell_id.id()]) self.assertEqual(cell_id, cu.cell_id(0)) def testEncodeDecode(self): cell_id = s2.S2CellId(s2.S2LatLng.FromDegrees(1.0, 2.0)).parent(10) cu = s2.S2CellUnion() cu.Init([cell_id.id()]) encoder = s2.Encoder() cu.Encode(encoder) decoder = s2.Decoder(encoder.buffer()) cu2 = s2.S2CellUnion() self.assertTrue(cu2.Decode(decoder)) self.assertEqual(cu.num_cells(), cu2.num_cells()) class S2LoopTest(unittest.TestCase): def _makeLoop(self): cell = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) return s2.S2Loop(cell) def testClone(self): loop = self._makeLoop() clone = loop.Clone() self.assertTrue(loop.Equals(clone)) def testEncodeDecode(self): loop = self._makeLoop() encoder = s2.Encoder() loop.Encode(encoder) decoder = s2.Decoder(encoder.buffer()) loop2 = s2.S2Loop() self.assertTrue(loop2.Decode(decoder)) self.assertTrue(loop.Equals(loop2)) def testGetCentroid(self): loop = self._makeLoop() centroid = loop.GetCentroid() self.assertIsInstance(centroid, s2.S2Point) def testGetDistance(self): loop = self._makeLoop() p = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() d = loop.GetDistance(p) self.assertIsInstance(d, s2.S1Angle) def testIntersects(self): loop1 = self._makeLoop() loop2 = self._makeLoop() self.assertTrue(loop1.Intersects(loop2)) def testProject(self): loop = self._makeLoop() p = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() projected = loop.Project(p) self.assertIsInstance(projected, s2.S2Point) def testIsEmpty(self): loop = self._makeLoop() self.assertFalse(loop.is_empty()) def testSign(self): loop = self._makeLoop() sign = loop.sign() self.assertEqual(1, sign) def testVertex(self): loop = self._makeLoop() v = loop.vertex(0) self.assertIsInstance(v, s2.S2Point) class S2PolylineTest(unittest.TestCase): def _makePolyline(self): line = s2.S2Polyline() line.InitFromS2LatLngs([ s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(1.0, 1.0), ]) return line def testClone(self): line = self._makePolyline() clone = line.Clone() self.assertTrue(line.ApproxEquals(clone)) def testEncodeDecode(self): line = self._makePolyline() encoder = s2.Encoder() line.Encode(encoder) decoder = s2.Decoder(encoder.buffer()) line2 = s2.S2Polyline() self.assertTrue(line2.Decode(decoder)) self.assertTrue(line.ApproxEquals(line2)) def testApproxEquals(self): line1 = self._makePolyline() line2 = self._makePolyline() self.assertTrue(line1.ApproxEquals(line2)) def testGetSuffix(self): line = self._makePolyline() point, next_vertex = line.GetSuffix(0.5) self.assertIsInstance(point, s2.S2Point) self.assertIsInstance(next_vertex, int) def testInterpolateAndUnInterpolate(self): line = self._makePolyline() p = line.Interpolate(0.5) self.assertIsInstance(p, s2.S2Point) f = line.UnInterpolate(p, 1) self.assertAlmostEqual(0.5, f, places=5) def testIntersects(self): line1 = s2.S2Polyline() line1.InitFromS2LatLngs([ s2.S2LatLng.FromDegrees(-1.0, 0.0), s2.S2LatLng.FromDegrees(1.0, 0.0), ]) line2 = s2.S2Polyline() line2.InitFromS2LatLngs([ s2.S2LatLng.FromDegrees(0.0, -1.0), s2.S2LatLng.FromDegrees(0.0, 1.0), ]) self.assertTrue(line1.Intersects(line2)) def testIsOnRight(self): line = self._makePolyline() p = s2.S2LatLng.FromDegrees(0.0, 1.0).ToPoint() result = line.IsOnRight(p) self.assertIsInstance(result, bool) def testIsValid(self): line = self._makePolyline() self.assertTrue(line.IsValid()) def testProject(self): line = self._makePolyline() p = s2.S2LatLng.FromDegrees(0.5, 0.5).ToPoint() projected = line.Project(p) self.assertIsInstance(projected[0], s2.S2Point) def testReverse(self): line = self._makePolyline() v0_before = s2.S2LatLng(line.vertex(0)).ToStringInDegrees() line.Reverse() v_last = s2.S2LatLng(line.vertex(0)).ToStringInDegrees() self.assertNotEqual(v0_before, v_last) def testNumVertices(self): line = self._makePolyline() self.assertEqual(2, line.num_vertices()) def testVertex(self): line = self._makePolyline() v = line.vertex(0) self.assertIsInstance(v, s2.S2Point) class S2EarthTest(unittest.TestCase): def testGetDistanceLatLng(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0) b = s2.S2LatLng.FromDegrees(1.0, 0.0) # GetDistance returns an opaque SWIG Meters* object. d = s2.S2Earth.GetDistance(a, b) self.assertTrue(d is not None) def testGetDistanceS2Point(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint() b = s2.S2LatLng.FromDegrees(1.0, 0.0).ToPoint() # GetDistance returns an opaque SWIG Meters* object. d = s2.S2Earth.GetDistance(a, b) self.assertTrue(d is not None) def testGetDistanceKmLatLng(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0) b = s2.S2LatLng.FromDegrees(1.0, 0.0) km = s2.S2Earth.GetDistanceKm(a, b) self.assertGreater(km, 100.0) def testGetDistanceKmS2Point(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint() b = s2.S2LatLng.FromDegrees(1.0, 0.0).ToPoint() km = s2.S2Earth.GetDistanceKm(a, b) self.assertGreater(km, 100.0) def testGetDistanceMetersLatLng(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0) b = s2.S2LatLng.FromDegrees(1.0, 0.0) m = s2.S2Earth.GetDistanceMeters(a, b) self.assertGreater(m, 100000.0) def testGetDistanceMetersS2Point(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0).ToPoint() b = s2.S2LatLng.FromDegrees(1.0, 0.0).ToPoint() m = s2.S2Earth.GetDistanceMeters(a, b) self.assertGreater(m, 100000.0) def testGetInitialBearing(self): a = s2.S2LatLng.FromDegrees(0.0, 0.0) b = s2.S2LatLng.FromDegrees(1.0, 0.0) bearing = s2.S2Earth.GetInitialBearing(a, b) self.assertIsInstance(bearing, s2.S1Angle) def testRadiusMethods(self): km = s2.S2Earth.RadiusKm() self.assertAlmostEqual(6371.01, km, places=1) m = s2.S2Earth.RadiusMeters() self.assertAlmostEqual(6371010.0, m, places=-1) def testAltitudeMethods(self): hm = s2.S2Earth.HighestAltitudeMeters() self.assertGreater(hm, 0.0) lom = s2.S2Earth.LowestAltitudeMeters() self.assertLess(lom, 0.0) def testMetersToRadians(self): r = s2.S2Earth.MetersToRadians(1000.0) self.assertGreater(r, 0.0) def testRadiansToKm(self): km = s2.S2Earth.RadiansToKm(0.001) self.assertGreater(km, 0.0) def testSquareConversions(self): sr = s2.S2Earth.SquareKmToSteradians(1.0) self.assertGreater(sr, 0.0) sr2 = s2.S2Earth.SquareMetersToSteradians(1000000.0) self.assertGreater(sr2, 0.0) km2 = s2.S2Earth.SteradiansToSquareKm(sr) self.assertAlmostEqual(1.0, km2, places=5) m2 = s2.S2Earth.SteradiansToSquareMeters(sr2) self.assertAlmostEqual(1000000.0, m2, places=0) def testToDistance(self): a = s2.S1Angle.Degrees(1.0) # ToDistance returns an opaque SWIG Meters* object. d = s2.S2Earth.ToDistance(a) self.assertTrue(d is not None) def testToDistanceChordAngle(self): ca = s2.S1ChordAngle(s2.S1Angle.Degrees(1.0)) # ToDistance returns an opaque SWIG Meters* object. d = s2.S2Earth.ToDistance(ca) self.assertTrue(d is not None) def testToKm(self): a = s2.S1Angle.Degrees(1.0) km = s2.S2Earth.ToKm(a) self.assertGreater(km, 100.0) def testToKmChordAngle(self): ca = s2.S1ChordAngle(s2.S1Angle.Degrees(1.0)) km = s2.S2Earth.ToKm(ca) self.assertGreater(km, 100.0) def testToMeters(self): a = s2.S1Angle.Degrees(1.0) m = s2.S2Earth.ToMeters(a) self.assertGreater(m, 100000.0) def testToMetersChordAngle(self): ca = s2.S1ChordAngle(s2.S1Angle.Degrees(1.0)) m = s2.S2Earth.ToMeters(ca) self.assertGreater(m, 100000.0) class S2LatLngTest(unittest.TestCase): def testFromE6(self): ll = s2.S2LatLng.FromE6(10000000, 20000000) self.assertAlmostEqual(10.0, ll.lat().degrees()) self.assertAlmostEqual(20.0, ll.lng().degrees()) def testFromE7(self): ll = s2.S2LatLng.FromE7(100000000, 200000000) self.assertAlmostEqual(10.0, ll.lat().degrees()) self.assertAlmostEqual(20.0, ll.lng().degrees()) def testFromRadians(self): ll = s2.S2LatLng.FromRadians(0.0, math.pi / 2) self.assertAlmostEqual(0.0, ll.lat().degrees()) self.assertAlmostEqual(90.0, ll.lng().degrees()) def testFromUnsignedE6(self): ll = s2.S2LatLng.FromUnsignedE6(10000000, 20000000) self.assertAlmostEqual(10.0, ll.lat().degrees()) self.assertAlmostEqual(20.0, ll.lng().degrees()) def testFromUnsignedE7(self): ll = s2.S2LatLng.FromUnsignedE7(100000000, 200000000) self.assertAlmostEqual(10.0, ll.lat().degrees()) self.assertAlmostEqual(20.0, ll.lng().degrees()) def testCoords(self): ll = s2.S2LatLng.FromDegrees(10.0, 20.0) # coords() returns an opaque SWIG R2Point object. c = ll.coords() self.assertTrue(c is not None) class S2LatLngRectTest(unittest.TestCase): def testFromPoint(self): r = s2.S2LatLngRect.FromPoint(s2.S2LatLng.FromDegrees(1.0, 2.0)) self.assertTrue(r.is_point()) def testFromPointPair(self): r = s2.S2LatLngRect.FromPointPair( s2.S2LatLng.FromDegrees(1.0, 2.0), s2.S2LatLng.FromDegrees(3.0, 4.0) ) self.assertFalse(r.is_empty()) def testFromCenterSize(self): center = s2.S2LatLng.FromDegrees(1.0, 2.0) size = s2.S2LatLng.FromDegrees(2.0, 4.0) r = s2.S2LatLngRect.FromCenterSize(center, size) self.assertFalse(r.is_empty()) def testEmpty(self): r = s2.S2LatLngRect.Empty() self.assertTrue(r.is_empty()) def testFull(self): r = s2.S2LatLngRect.Full() self.assertFalse(r.is_empty()) def testExpandedByDistance(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(1.0, 2.0), s2.S2LatLng.FromDegrees(3.0, 4.0) ) expanded = r.ExpandedByDistance(s2.S1Angle.Degrees(1.0)) self.assertGreater(expanded.Area(), r.Area()) def testArea(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(1.0, 1.0) ) self.assertGreater(r.Area(), 0.0) def testGetCenter(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(2.0, 4.0) ) c = r.GetCenter() self.assertAlmostEqual(1.0, c.lat().degrees()) self.assertAlmostEqual(2.0, c.lng().degrees()) def testGetCentroid(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(2.0, 4.0) ) centroid = r.GetCentroid() self.assertIsInstance(centroid, s2.S2Point) def testGetDistance(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(1.0, 1.0) ) p = s2.S2LatLng.FromDegrees(5.0, 5.0) d = r.GetDistance(p) self.assertIsInstance(d, s2.S1Angle) def testGetSize(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(2.0, 4.0) ) size = r.GetSize() self.assertAlmostEqual(2.0, size.lat().degrees()) self.assertAlmostEqual(4.0, size.lng().degrees()) def testGetVertex(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(2.0, 4.0) ) for i in range(4): v = r.GetVertex(i) self.assertIsInstance(v, s2.S2LatLng) def testIntersectionAndUnion(self): r1 = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(0.0, 0.0), s2.S2LatLng.FromDegrees(2.0, 2.0) ) r2 = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(1.0, 1.0), s2.S2LatLng.FromDegrees(3.0, 3.0) ) inter = r1.Intersection(r2) self.assertFalse(inter.is_empty()) union = r1.Union(r2) self.assertGreater(union.Area(), r1.Area()) def testLatLngAccessors(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(1.0, 2.0), s2.S2LatLng.FromDegrees(3.0, 4.0) ) self.assertAlmostEqual(1.0, r.lat_lo().degrees()) self.assertAlmostEqual(3.0, r.lat_hi().degrees()) self.assertAlmostEqual(2.0, r.lng_lo().degrees()) self.assertAlmostEqual(4.0, r.lng_hi().degrees()) # lat()/lng() return opaque SWIG R1Interval/S1Interval objects. self.assertTrue(r.lat() is not None) self.assertTrue(r.lng() is not None) self.assertIsInstance(r.lo(), s2.S2LatLng) self.assertIsInstance(r.hi(), s2.S2LatLng) def testEncodeDecode(self): r = s2.S2LatLngRect( s2.S2LatLng.FromDegrees(1.0, 2.0), s2.S2LatLng.FromDegrees(3.0, 4.0) ) encoder = s2.Encoder() r.Encode(encoder) decoder = s2.Decoder(encoder.buffer()) r2 = s2.S2LatLngRect() self.assertTrue(r2.Decode(decoder)) self.assertTrue(r.ApproxEquals(r2)) def testAddPoint(self): r = s2.S2LatLngRect.Empty() r.AddPoint(s2.S2LatLng.FromDegrees(1.0, 2.0)) self.assertFalse(r.is_empty()) class EncoderDecoderTest(unittest.TestCase): def testPutGet8(self): enc = s2.Encoder() enc.Ensure(1) enc.put8(42) dec = s2.Decoder(enc.buffer()) self.assertEqual(42, dec.get8()) def testPutGet16(self): enc = s2.Encoder() enc.Ensure(2) enc.put16(1234) dec = s2.Decoder(enc.buffer()) self.assertEqual(1234, dec.get16()) def testPutGet32(self): enc = s2.Encoder() enc.Ensure(4) enc.put32(12345678) dec = s2.Decoder(enc.buffer()) self.assertEqual(12345678, dec.get32()) def testPutGet64(self): enc = s2.Encoder() enc.Ensure(8) enc.put64(123456789012345) dec = s2.Decoder(enc.buffer()) self.assertEqual(123456789012345, dec.get64()) def testPutGetFloat(self): enc = s2.Encoder() enc.Ensure(4) enc.putfloat(3.14) dec = s2.Decoder(enc.buffer()) self.assertAlmostEqual(3.14, dec.getfloat(), places=5) def testPutGetDouble(self): enc = s2.Encoder() enc.Ensure(8) enc.putdouble(3.141592653589793) dec = s2.Decoder(enc.buffer()) self.assertAlmostEqual(3.141592653589793, dec.getdouble()) def testEncoderLengthAndAvail(self): enc = s2.Encoder() self.assertEqual(0, enc.length()) enc.Ensure(1) enc.put8(1) self.assertEqual(1, enc.length()) self.assertGreaterEqual(enc.avail(), 0) def testEncoderClear(self): enc = s2.Encoder() enc.Ensure(1) enc.put8(1) enc.clear() self.assertEqual(0, enc.length()) def testEncoderEnsure(self): enc = s2.Encoder() enc.Ensure(100) self.assertGreaterEqual(enc.avail(), 100) def testDecoderPosAndAvail(self): enc = s2.Encoder() enc.Ensure(2) enc.put8(1) enc.put8(2) dec = s2.Decoder(enc.buffer()) self.assertEqual(0, dec.pos()) self.assertEqual(2, dec.avail()) dec.get8() self.assertEqual(1, dec.pos()) self.assertEqual(1, dec.avail()) class RegionTermIndexerTest(unittest.TestCase): def _randomCaps(self, query_type, **indexer_options): # This function creates an index consisting either of points (if # options.index_contains_points_only() is true) or S2Caps of random size. # It then executes queries consisting of points (if query_type == POINT) # or S2Caps of random size (if query_type == CAP). # # indexer_options are set on both the indexer & coverer (if relevant) # eg. _randomCaps('cap', min_level=0) calls indexer.set_min_level(0) ITERATIONS = 400 indexer = s2.S2RegionTermIndexer() coverer = s2.S2RegionCoverer() # set indexer options for opt_key, opt_value in indexer_options.items(): setter = "set_%s" % opt_key getattr(indexer, setter)(opt_value) if hasattr(coverer, setter): getattr(coverer, setter)(opt_value) caps = [] coverings = [] index = defaultdict(set) index_terms = 0 query_terms = 0 for i in range(ITERATIONS): # Choose the region to be indexed: either a single point or a cap # of random size (up to a full sphere). terms = [] if indexer.index_contains_points_only(): cap = s2.S2Cap.FromPoint(s2.S2Testing.RandomPoint()) terms = indexer.GetIndexTerms(cap.center(), "") else: cap = s2.S2Testing.GetRandomCap( 0.3 * s2.S2Cell.AverageArea(indexer.max_level()), 4.0 * s2.S2Cell.AverageArea(indexer.min_level()), ) terms = indexer.GetIndexTerms(cap, "") caps.append(cap) coverings.append(s2.S2CellUnion(coverer.GetCovering(cap))) for term in terms: index[term].add(i) index_terms += len(terms) for i in range(ITERATIONS): # Choose the region to be queried: either a random point or a cap of # random size. terms = [] if query_type == "cap": cap = s2.S2Cap.FromPoint(s2.S2Testing.RandomPoint()) terms = indexer.GetQueryTerms(cap.center(), "") else: cap = s2.S2Testing.GetRandomCap( 0.3 * s2.S2Cell.AverageArea(indexer.max_level()), 4.0 * s2.S2Cell.AverageArea(indexer.min_level()), ) terms = indexer.GetQueryTerms(cap, "") # Compute the expected results of the S2Cell query by brute force. covering = s2.S2CellUnion(coverer.GetCovering(cap)) expected, actual = set(), set() for j in range(len(caps)): if covering.Intersects(coverings[j]): expected.add(j) for term in terms: actual |= index[term] self.assertEqual(expected, actual) query_terms += len(terms) print( "Index terms/doc: %0.2f, Query terms/doc: %0.2f" % ( float(index_terms) / ITERATIONS, float(query_terms) / ITERATIONS, ) ) # We run one test case for each combination of space vs. time optimization, # and indexing regions vs. only points. def testIndexRegionsQueryRegionsOptimizeTime(self): self._randomCaps( "cap", optimize_for_space=False, min_level=0, max_level=16, max_cells=20, ) def testIndexRegionsQueryPointsOptimizeTime(self): self._randomCaps( "point", optimize_for_space=False, min_level=0, max_level=16, max_cells=20, ) def testIndexRegionsQueryRegionsOptimizeTimeWithLevelMod(self): self._randomCaps( "cap", optimize_for_space=False, min_level=6, max_level=12, level_mod=3, ) def testIndexRegionsQueryRegionsOptimizeSpace(self): self._randomCaps( "cap", optimize_for_space=True, min_level=4, max_level=s2.S2CellId.kMaxLevel, max_cells=8, ) def testIndexPointsQueryRegionsOptimizeTime(self): self._randomCaps( "cap", optimize_for_space=False, min_level=0, max_level=s2.S2CellId.kMaxLevel, level_mod=2, max_cells=20, index_contains_points_only=True, ) def testIndexPointsQueryRegionsOptimizeSpace(self): self._randomCaps( "cap", optimize_for_space=True, index_contains_points_only=True, ) def testMaxLevelSetLoosely(self): # Test that correct terms are generated even when (max_level - min_level) # is not a multiple of level_mod. indexer1 = s2.S2RegionTermIndexer() indexer1.set_min_level(1) indexer1.set_level_mod(2) indexer1.set_max_level(19) indexer2 = s2.S2RegionTermIndexer() indexer2.set_min_level(1) indexer2.set_level_mod(2) indexer2.set_max_level(19) indexer2.set_max_level(20) point = s2.S2Testing.RandomPoint() self.assertEqual( indexer1.GetIndexTerms(point, ""), indexer2.GetIndexTerms(point, "") ) self.assertEqual( indexer1.GetQueryTerms(point, ""), indexer2.GetQueryTerms(point, "") ) cap = s2.S2Testing.GetRandomCap(0.0, 1.0) self.assertEqual( indexer1.GetIndexTerms(cap, ""), indexer2.GetIndexTerms(cap, "") ) self.assertEqual( indexer1.GetQueryTerms(cap, ""), indexer2.GetQueryTerms(cap, "") ) def testS2CellIdFromDebugString(self): cell = s2.S2CellId.FromDebugString("5/31200") self.assertTrue(cell.is_valid()) self.assertEqual("5/31200", cell.ToString()) def testCovererSetFixedLevel(self): coverer = s2.S2RegionCoverer() coverer.set_fixed_level(10) self.assertEqual(10, coverer.min_level()) self.assertEqual(10, coverer.max_level()) def testCovererTrueMaxLevel(self): coverer = s2.S2RegionCoverer() coverer.set_max_level(20) self.assertEqual(20, coverer.true_max_level()) def testIndexerMarkerCharacter(self): indexer = s2.S2RegionTermIndexer() default_marker = indexer.marker_character() self.assertIsInstance(default_marker, str) def testIndexerTrueMaxLevel(self): indexer = s2.S2RegionTermIndexer() indexer.set_max_level(20) self.assertEqual(20, indexer.true_max_level()) def testIndexerSetFixedLevel(self): indexer = s2.S2RegionTermIndexer() indexer.set_fixed_level(10) self.assertEqual(10, indexer.min_level()) self.assertEqual(10, indexer.max_level()) class S2PolygonTestCase(unittest.TestCase): def _makePolygon(self): cell = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) return s2.S2Polygon(cell) def testInitToUnionSame(self): cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) polygon1 = s2.S2Polygon(cell1) cell2 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) polygon2 = s2.S2Polygon(cell2) polygon3 = s2.S2Polygon() polygon3.InitToUnion(polygon1, polygon2) self.assertEqual(1, polygon3.num_loops()) loop = polygon3.loop(0) self.assertEqual(4, loop.num_vertices()) def testInitToUnionDistinct(self): cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) polygon1 = s2.S2Polygon(cell1) cell2 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(13.0, 4.0)).parent(8) ) polygon2 = s2.S2Polygon(cell2) polygon3 = s2.S2Polygon() polygon3.InitToUnion(polygon1, polygon2) self.assertEqual(2, polygon3.num_loops()) loop = polygon3.loop(0) self.assertEqual(4, loop.num_vertices()) loop = polygon3.loop(1) self.assertEqual(4, loop.num_vertices()) def testClone(self): poly = self._makePolygon() clone = poly.Clone() self.assertTrue(poly.Equals(clone)) def testCopy(self): poly = self._makePolygon() copy = s2.S2Polygon() copy.Copy(poly) self.assertTrue(poly.Equals(copy)) def testGetCentroid(self): poly = self._makePolygon() centroid = poly.GetCentroid() self.assertIsInstance(centroid, s2.S2Point) def testGetDistance(self): poly = self._makePolygon() p = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() d = poly.GetDistance(p) self.assertIsInstance(d, s2.S1Angle) def testProject(self): poly = self._makePolygon() p = s2.S2LatLng.FromDegrees(3.0, 4.0).ToPoint() projected = poly.Project(p) self.assertIsInstance(projected, s2.S2Point) def testIsEmpty(self): empty = s2.S2Polygon() self.assertTrue(empty.is_empty()) poly = self._makePolygon() self.assertFalse(poly.is_empty()) def testNumVertices(self): poly = self._makePolygon() self.assertEqual(4, poly.num_vertices()) def testIntersects(self): poly1 = self._makePolygon() poly2 = self._makePolygon() self.assertTrue(poly1.Intersects(poly2)) def testIsValid(self): poly = self._makePolygon() self.assertTrue(poly.IsValid()) class S2ChordAngleTest(unittest.TestCase): def testBasic(self): ca = s2.S1ChordAngle(s2.S1Angle.Degrees(100)) self.assertAlmostEqual(100, ca.degrees()) def testArithmetic(self): ca1 = s2.S1ChordAngle(s2.S1Angle.Degrees(10)) ca2 = s2.S1ChordAngle(s2.S1Angle.Degrees(20)) ca3 = ca1 + ca2 self.assertAlmostEqual(30, ca3.degrees()) ca4 = ca2 - ca1 self.assertAlmostEqual(10, ca4.degrees()) def testComparison(self): ca1 = s2.S1ChordAngle(s2.S1Angle.Degrees(10)) ca2 = s2.S1ChordAngle(s2.S1Angle.Degrees(20)) self.assertTrue(ca1 < ca2) self.assertTrue(ca2 > ca1) self.assertFalse(ca1 > ca2) self.assertFalse(ca2 < ca1) ca3 = s2.S1ChordAngle(s2.S1Angle.Degrees(10)) self.assertTrue(ca1 == ca3) self.assertFalse(ca1 == ca2) self.assertFalse(ca1 != ca3) self.assertTrue(ca1 != ca2) def testInfinity(self): ca1 = s2.S1ChordAngle(s2.S1Angle.Degrees(179)) ca2 = s2.S1ChordAngle.Infinity() self.assertTrue(ca2 > ca1) def testCopy(self): ca1 = s2.S1ChordAngle(s2.S1Angle.Degrees(100)) ca2 = s2.S1ChordAngle(ca1) self.assertAlmostEqual(100, ca2.degrees()) def testToAngle(self): ca = s2.S1ChordAngle(s2.S1Angle.Degrees(90.0)) a = ca.ToAngle() self.assertAlmostEqual(90.0, a.degrees()) class S2BufferOperationTest(unittest.TestCase): def setUp(self): self.opts = s2.S2BufferOperationOptions() self.result = s2.S2Polygon() self.layer = s2.S2PolygonLayer(self.result) def testDefaults(self): op = s2.S2BufferOperation(self.layer, self.opts) cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) op.AddPolygon(s2.S2Polygon(cell1)) op.Build() self.assertEqual(1, self.result.num_loops()) loop = self.result.loop(0) self.assertEqual(4, loop.num_vertices()) def testRadius(self): self.opts.set_buffer_radius(s2.S1Angle.Degrees(0.001)) op = s2.S2BufferOperation(self.layer, self.opts) cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) op.AddPolygon(s2.S2Polygon(cell1)) op.Build() self.assertEqual(1, self.result.num_loops()) loop = self.result.loop(0) self.assertEqual(20, loop.num_vertices()) def testRadiusAndError(self): self.opts.set_buffer_radius(s2.S1Angle.Degrees(0.001)) self.opts.set_error_fraction(0.1) op = s2.S2BufferOperation(self.layer, self.opts) cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) op.AddPolygon(s2.S2Polygon(cell1)) op.Build() self.assertEqual(1, self.result.num_loops()) loop = self.result.loop(0) self.assertEqual(12, loop.num_vertices()) def testPoint(self): self.opts.set_buffer_radius(s2.S1Angle.Degrees(0.001)) op = s2.S2BufferOperation(self.layer, self.opts) op.AddPoint(s2.S2LatLng.FromDegrees(14.0, 15.0).ToPoint()) op.Build() self.assertEqual(1, self.result.num_loops()) loop = self.result.loop(0) self.assertEqual(16, loop.num_vertices()) class S2BooleanOperationTest(unittest.TestCase): def setUp(self): self.index1 = s2.MutableS2ShapeIndex() self.index2 = s2.MutableS2ShapeIndex() def operate(self): poly = s2.S2Polygon() layer = s2.S2PolygonLayer(poly) op = s2.S2BooleanOperation(s2.S2BooleanOperation.OpType_UNION, layer) op.Build(self.index1, self.index2) return poly def testUnionSame(self): cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) self.index1.Add(s2.S2Polygon(cell1)) cell2 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) self.index2.Add(s2.S2Polygon(cell2)) result = self.operate() self.assertEqual(1, result.num_loops()) loop = result.loop(0) self.assertEqual(4, loop.num_vertices()) def testUnionDistinct(self): cell1 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(3.0, 4.0)).parent(8) ) self.index1.Add(s2.S2Polygon(cell1)) cell2 = s2.S2Cell( s2.S2CellId(s2.S2LatLng.FromDegrees(13.0, 4.0)).parent(8) ) self.index2.Add(s2.S2Polygon(cell2)) result = self.operate() self.assertEqual(2, result.num_loops()) loop = result.loop(0) self.assertEqual(4, loop.num_vertices()) loop = result.loop(1) self.assertEqual(4, loop.num_vertices()) # See https://github.com/google/s2geometry/issues/376 @unittest.skip("CHECK-fails in debug mode.") class S2BuilderTest(unittest.TestCase): def setUp(self): self.p1 = s2.S2LatLng.FromDegrees(10.0, 10.0).ToPoint() self.p2 = s2.S2LatLng.FromDegrees(10.0, 11.0).ToPoint() self.p3 = s2.S2LatLng.FromDegrees(11.0, 10.0).ToPoint() self.p4 = s2.S2LatLng.FromDegrees(11.0, 11.0).ToPoint() def testSquareDirected(self): opts = s2.S2PolygonLayerOptions() opts.set_edge_type(s2.S2Builder.EdgeType_DIRECTED) result = s2.S2Polygon() b = s2.S2Builder() b.StartLayer(s2.S2PolygonLayer(result, opts)) b.AddEdge(self.p1, self.p2) b.AddEdge(self.p2, self.p4) b.AddEdge(self.p4, self.p3) b.AddEdge(self.p3, self.p1) b.Build() self.assertEqual(1, result.num_loops()) loop = result.loop(0) self.assertEqual(4, loop.num_vertices()) def testSquareUndirected(self): opts = s2.S2PolygonLayerOptions() opts.set_edge_type(s2.S2Builder.EdgeType_UNDIRECTED) result = s2.S2Polygon() b = s2.S2Builder() b.StartLayer(s2.S2PolygonLayer(result, opts)) b.AddEdge(self.p1, self.p2) b.AddEdge(self.p1, self.p3) b.AddEdge(self.p2, self.p4) b.AddEdge(self.p3, self.p4) b.Build() self.assertEqual(1, result.num_loops()) loop = result.loop(0) self.assertEqual(4, loop.num_vertices()) def testException(self): opts = s2.S2PolygonLayerOptions() opts.set_edge_type(s2.S2Builder.EdgeType_DIRECTED) result = s2.S2Polygon() b = s2.S2Builder() b.StartLayer(s2.S2PolygonLayer(result, opts)) b.AddEdge(self.p1, self.p2) b.AddEdge(self.p1, self.p3) b.AddEdge(self.p2, self.p4) b.AddEdge(self.p3, self.p4) with self.assertRaises(ValueError): b.Build() if __name__ == "__main__": unittest.main() src/python/s2latlng_bindings.cc000066400000000000000000000206541524103652300171100ustar00rootroot00000000000000#include #include #include #include #include "absl/hash/hash.h" #include "absl/strings/str_cat.h" #include "s2/s1angle.h" #include "s2/s2latlng.h" #include "s2/s2point.h" namespace py = pybind11; namespace { void MaybeThrowNotValid(const S2LatLng& ll) { if (!ll.is_valid()) { throw py::value_error(absl::StrCat( "Invalid S2LatLng: (", ll.lat().degrees(), ", ", ll.lng().degrees(), ") (latitude must be in [-90, 90], longitude in [-180, 180])")); } } void MaybeThrowNotFinite(double m) { if (!std::isfinite(m)) { throw py::value_error(absl::StrCat("Scalar must be finite, got ", m)); } } } // namespace void bind_s2latlng(py::module& m) { py::class_(m, "S2LatLng", "Represents a point on the unit sphere as a latitude-longitude pair.\n\n" "All S2LatLng values are guaranteed to be valid: latitude in [-90, 90]\n" "and longitude in [-180, 180] degrees. Constructors and factory methods\n" "raise ValueError for out-of-range inputs. Arithmetic operators\n" "automatically normalize the result.\n\n" "Note: the native C++ implementation does not normalize arithmetic\n" "results and allows invalid states.\n\n" "See s2/s2latlng.h for comprehensive documentation.") // Constructors .def(py::init<>(), "Default constructor sets latitude and longitude to zero") .def(py::init([](S1Angle lat, S1Angle lng) { S2LatLng ll(lat, lng); MaybeThrowNotValid(ll); return ll; }), py::arg("lat"), py::arg("lng"), "Construct from latitude and longitude angles.\n\n" "Raises ValueError if latitude is not in [-90, 90] or\n" "longitude is not in [-180, 180] degrees.") .def(py::init([](const S2Point& p) { S2LatLng ll(p); MaybeThrowNotValid(ll); return ll; }), py::arg("point"), "Convert a direction vector to an S2LatLng.\n\n" "The vector does not need to be unit length.\n" "Raises ValueError if the point has non-finite coordinates.") // Factory methods .def_static("from_radians", [](double lat_radians, double lng_radians) { S2LatLng ll = S2LatLng::FromRadians(lat_radians, lng_radians); MaybeThrowNotValid(ll); return ll; }, py::arg("lat_radians"), py::arg("lng_radians"), "Construct from latitude and longitude in radians.\n\n" "Raises ValueError if out of range.") .def_static("normalized_from_radians", [](double lat_radians, double lng_radians) { MaybeThrowNotFinite(lat_radians); MaybeThrowNotFinite(lng_radians); return S2LatLng::FromRadians(lat_radians, lng_radians) .Normalized(); }, py::arg("lat_radians"), py::arg("lng_radians"), "Construct from latitude and longitude in radians, accepting any\n" "finite values. Latitude is clamped to [-Pi/2, Pi/2] and longitude\n" "is wrapped to [-Pi, Pi].\n\n" "Raises ValueError if either value is non-finite.") .def_static("from_degrees", [](double lat_degrees, double lng_degrees) { S2LatLng ll = S2LatLng::FromDegrees(lat_degrees, lng_degrees); MaybeThrowNotValid(ll); return ll; }, py::arg("lat_degrees"), py::arg("lng_degrees"), "Construct from latitude and longitude in degrees.\n\n" "Raises ValueError if out of range.") .def_static("from_e5", [](int32_t lat_e5, int32_t lng_e5) { S2LatLng ll = S2LatLng::FromE5(lat_e5, lng_e5); MaybeThrowNotValid(ll); return ll; }, py::arg("lat_e5"), py::arg("lng_e5"), "Construct from latitude and longitude in E5 format.\n\n" "Raises ValueError if out of range.") .def_static("from_e6", [](int32_t lat_e6, int32_t lng_e6) { S2LatLng ll = S2LatLng::FromE6(lat_e6, lng_e6); MaybeThrowNotValid(ll); return ll; }, py::arg("lat_e6"), py::arg("lng_e6"), "Construct from latitude and longitude in E6 format.\n\n" "Raises ValueError if out of range.") .def_static("from_e7", [](int32_t lat_e7, int32_t lng_e7) { S2LatLng ll = S2LatLng::FromE7(lat_e7, lng_e7); MaybeThrowNotValid(ll); return ll; }, py::arg("lat_e7"), py::arg("lng_e7"), "Construct from latitude and longitude in E7 format.\n\n" "Raises ValueError if out of range.") .def_static("latitude", &S2LatLng::Latitude, py::arg("point"), "Return the latitude of a direction vector") .def_static("longitude", &S2LatLng::Longitude, py::arg("point"), "Return the longitude of a direction vector") // Properties .def_property_readonly("lat", &S2LatLng::lat, "The latitude as an S1Angle") .def_property_readonly("lng", &S2LatLng::lng, "The longitude as an S1Angle") .def_property_readonly("coords", &S2LatLng::coords, "The (lat, lng) coordinates in radians as an R2Point") // Geometric operations .def("to_point", &S2LatLng::ToPoint, "Convert to the equivalent unit-length S2Point") .def("distance", &S2LatLng::GetDistance, py::arg("other"), "Return the surface distance to another S2LatLng.\n\n" "Uses the Haversine formula.") // Note: default value must match C++ signature in s2latlng.h .def("approx_equals", [](const S2LatLng& self, const S2LatLng& o, S1Angle max_error) { return self.ApproxEquals(o, max_error); }, py::arg("other"), py::arg("max_error") = S1Angle::Radians(1e-15), "Return true if approximately equal to 'other'.\n\n" "Note: this compares coordinates in rectangular lat/lng space.\n" "For points near the poles, consider using distance() instead.") // Operators .def(py::self == py::self, "Return true if exactly equal") .def(py::self != py::self, "Return true if not exactly equal") .def(py::self < py::self, "Compare by latitude first, then longitude") .def(py::self > py::self, "Compare by latitude first, then longitude") .def(py::self <= py::self, "Compare by latitude first, then longitude") .def(py::self >= py::self, "Compare by latitude first, then longitude") .def("__add__", [](const S2LatLng& a, const S2LatLng& b) { return (a + b).Normalized(); }, py::arg("other"), "Add two S2LatLngs.\n\n" "The result is automatically normalized.\n" "Note: the native C++ implementation does not normalize.") .def("__sub__", [](const S2LatLng& a, const S2LatLng& b) { return (a - b).Normalized(); }, py::arg("other"), "Subtract two S2LatLngs.\n\n" "The result is automatically normalized.\n" "Note: the native C++ implementation does not normalize.") .def("__mul__", [](const S2LatLng& a, double m) { MaybeThrowNotFinite(m); return (a * m).Normalized(); }, py::arg("m"), "Multiply by scalar.\n\n" "The result is automatically normalized.\n" "Note: the native C++ implementation does not normalize.") .def("__rmul__", [](const S2LatLng& a, double m) { MaybeThrowNotFinite(m); return (m * a).Normalized(); }, py::arg("m"), "Multiply by scalar (reversed operands).\n\n" "The result is automatically normalized.\n" "Note: the native C++ implementation does not normalize.") .def("__hash__", [](const S2LatLng& self) { return absl::HashOf(self); }) // String representation .def("to_string_in_degrees", &S2LatLng::ToStringInDegrees, "Return \"lat,lng\" in degrees, e.g. \"37.794000,-122.395000\"") .def("__repr__", [](const S2LatLng& ll) { std::ostringstream oss; oss << "S2LatLng(" << ll << ")"; return oss.str(); }) .def("__str__", [](const S2LatLng& ll) { std::ostringstream oss; oss << ll; return oss.str(); }); } src/python/s2latlng_test.py000066400000000000000000000276641524103652300163450ustar00rootroot00000000000000"""Tests for S2LatLng pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS2LatLng(unittest.TestCase): """Test cases for S2LatLng bindings.""" # Constructors def test_default_constructor(self): ll = s2.S2LatLng() self.assertEqual(ll.lat.radians, 0.0) self.assertEqual(ll.lng.radians, 0.0) def test_constructor_from_angles(self): lat = s2.S1Angle.from_degrees(37.0) lng = s2.S1Angle.from_degrees(-122.0) ll = s2.S2LatLng(lat, lng) self.assertAlmostEqual(ll.lat.degrees, 37.0) self.assertAlmostEqual(ll.lng.degrees, -122.0) def test_constructor_from_angles_at_bounds(self): ll = s2.S2LatLng( s2.S1Angle.from_degrees(90.0), s2.S1Angle.from_degrees(180.0) ) self.assertAlmostEqual(ll.lat.degrees, 90.0) self.assertAlmostEqual(ll.lng.degrees, 180.0) def test_constructor_from_angles_invalid_lat_raises(self): with self.assertRaises(ValueError) as cm: s2.S2LatLng( s2.S1Angle.from_degrees(91.0), s2.S1Angle.from_degrees(0.0) ) self.assertEqual( str(cm.exception), "Invalid S2LatLng: (91, 0) " "(latitude must be in [-90, 90], longitude in [-180, 180])", ) def test_constructor_from_angles_invalid_lng_raises(self): with self.assertRaises(ValueError): s2.S2LatLng( s2.S1Angle.from_degrees(0.0), s2.S1Angle.from_degrees(181.0) ) def test_constructor_from_point(self): p = s2.S2Point(1.0, 0.0, 0.0) ll = s2.S2LatLng(p) self.assertAlmostEqual(ll.lat.degrees, 0.0) self.assertAlmostEqual(ll.lng.degrees, 0.0) def test_constructor_from_nan_point_raises(self): p = s2.S2Point(float("nan"), 0.0, 0.0) with self.assertRaises(ValueError): s2.S2LatLng(p) def test_constructor_from_point_north_pole(self): p = s2.S2Point(0.0, 0.0, 1.0) ll = s2.S2LatLng(p) self.assertAlmostEqual(ll.lat.degrees, 90.0) # Factory methods def test_from_radians(self): ll = s2.S2LatLng.from_radians(math.pi / 4, -math.pi / 2) self.assertAlmostEqual(ll.lat.degrees, 45.0) self.assertAlmostEqual(ll.lng.degrees, -90.0) def test_from_radians_invalid_raises(self): with self.assertRaises(ValueError): s2.S2LatLng.from_radians(2.0, 0.0) # lat > pi/2 def test_normalized_from_radians_clamps_latitude(self): ll = s2.S2LatLng.normalized_from_radians(2.0, 0.0) # lat > pi/2 self.assertAlmostEqual(ll.lat.radians, math.pi / 2) self.assertAlmostEqual(ll.lng.radians, 0.0) def test_normalized_from_radians_wraps_longitude(self): # 3*pi/2 wraps to -pi/2 ll = s2.S2LatLng.normalized_from_radians(0.0, 3 * math.pi / 2) self.assertAlmostEqual(ll.lat.radians, 0.0) self.assertAlmostEqual(ll.lng.radians, -math.pi / 2) def test_normalized_from_radians_in_range_is_unchanged(self): ll = s2.S2LatLng.normalized_from_radians(0.5, -1.0) self.assertAlmostEqual(ll.lat.radians, 0.5) self.assertAlmostEqual(ll.lng.radians, -1.0) def test_normalized_from_radians_non_finite_raises(self): with self.assertRaises(ValueError): s2.S2LatLng.normalized_from_radians(float("nan"), 0.0) with self.assertRaises(ValueError): s2.S2LatLng.normalized_from_radians(0.0, float("inf")) def test_from_degrees(self): ll = s2.S2LatLng.from_degrees(45.0, -90.0) self.assertAlmostEqual(ll.lat.degrees, 45.0) self.assertAlmostEqual(ll.lng.degrees, -90.0) def test_from_degrees_invalid_raises(self): with self.assertRaises(ValueError): s2.S2LatLng.from_degrees(91.0, 0.0) with self.assertRaises(ValueError): s2.S2LatLng.from_degrees(0.0, 181.0) def test_from_e5(self): ll = s2.S2LatLng.from_e5(4500000, -9000000) self.assertAlmostEqual(ll.lat.degrees, 45.0) self.assertAlmostEqual(ll.lng.degrees, -90.0) def test_from_e5_invalid_raises(self): with self.assertRaises(ValueError): s2.S2LatLng.from_e5(9100000, 0) # 91 degrees def test_from_e6(self): ll = s2.S2LatLng.from_e6(45000000, -90000000) self.assertAlmostEqual(ll.lat.degrees, 45.0) self.assertAlmostEqual(ll.lng.degrees, -90.0) def test_from_e6_invalid_raises(self): with self.assertRaises(ValueError): s2.S2LatLng.from_e6(91000000, 0) # 91 degrees def test_from_e7(self): ll = s2.S2LatLng.from_e7(450000000, -900000000) self.assertAlmostEqual(ll.lat.degrees, 45.0) self.assertAlmostEqual(ll.lng.degrees, -90.0) def test_from_e7_invalid_raises(self): with self.assertRaises(ValueError): s2.S2LatLng.from_e7(910000000, 0) # 91 degrees def test_latitude_static(self): p = s2.S2Point(0.0, 0.0, 1.0) lat = s2.S2LatLng.latitude(p) self.assertAlmostEqual(lat.degrees, 90.0) def test_longitude_static(self): p = s2.S2Point(0.0, 1.0, 0.0) lng = s2.S2LatLng.longitude(p) self.assertAlmostEqual(lng.degrees, 90.0) # Properties def test_lat_lng_are_s1angles(self): ll = s2.S2LatLng.from_degrees(37.0, -122.0) self.assertIsInstance(ll.lat, s2.S1Angle) self.assertIsInstance(ll.lng, s2.S1Angle) def test_lat_lng_readonly(self): ll = s2.S2LatLng.from_degrees(37.0, -122.0) with self.assertRaises(AttributeError): ll.lat = s2.S1Angle.from_degrees(0.0) with self.assertRaises(AttributeError): ll.lng = s2.S1Angle.from_degrees(0.0) def test_coords(self): ll = s2.S2LatLng.from_radians(0.5, -1.0) coords = ll.coords self.assertIsInstance(coords, s2.R2Point) self.assertAlmostEqual(coords.x, 0.5) self.assertAlmostEqual(coords.y, -1.0) # Geometric operations def test_to_point(self): ll = s2.S2LatLng.from_degrees(0.0, 0.0) p = ll.to_point() self.assertAlmostEqual(p.x, 1.0) self.assertAlmostEqual(p.y, 0.0) self.assertAlmostEqual(p.z, 0.0) def test_to_point_north_pole(self): ll = s2.S2LatLng.from_degrees(90.0, 0.0) p = ll.to_point() self.assertAlmostEqual(p.x, 0.0, places=15) self.assertAlmostEqual(p.y, 0.0, places=15) self.assertAlmostEqual(p.z, 1.0) def test_to_point_roundtrip(self): ll = s2.S2LatLng.from_degrees(37.7749, -122.4194) p = ll.to_point() ll2 = s2.S2LatLng(p) self.assertAlmostEqual(ll.lat.radians, ll2.lat.radians) self.assertAlmostEqual(ll.lng.radians, ll2.lng.radians) def test_distance(self): # Distance between two points on the equator, 90 degrees apart. a = s2.S2LatLng.from_degrees(0.0, 0.0) b = s2.S2LatLng.from_degrees(0.0, 90.0) self.assertAlmostEqual(a.distance(b).degrees, 90.0) def test_distance_same_point(self): ll = s2.S2LatLng.from_degrees(37.0, -122.0) self.assertAlmostEqual(ll.distance(ll).radians, 0.0) def test_to_string_in_degrees(self): ll = s2.S2LatLng.from_degrees(37.794, -122.395) self.assertEqual(ll.to_string_in_degrees(), "37.794000,-122.395000") def test_approx_equals(self): a = s2.S2LatLng.from_degrees(37.0, -122.0) b = s2.S2LatLng.from_degrees(37.0, -122.0) self.assertTrue(a.approx_equals(b)) def test_approx_equals_within_tolerance(self): a = s2.S2LatLng.from_degrees(37.0, -122.0) b = s2.S2LatLng.from_degrees(37.0 + 1e-16, -122.0) self.assertTrue(a.approx_equals(b)) def test_approx_equals_outside_default_tolerance(self): a = s2.S2LatLng.from_degrees(37.0, -122.0) b = s2.S2LatLng.from_degrees(37.1, -122.0) self.assertFalse(a.approx_equals(b)) def test_approx_equals_custom_tolerance(self): a = s2.S2LatLng.from_degrees(37.0, -122.0) b = s2.S2LatLng.from_degrees(37.1, -122.0) self.assertTrue(a.approx_equals(b, s2.S1Angle.from_degrees(0.2))) self.assertFalse(a.approx_equals(b, s2.S1Angle.from_degrees(0.05))) # Operators def test_equality(self): a = s2.S2LatLng.from_degrees(37.0, -122.0) b = s2.S2LatLng.from_degrees(37.0, -122.0) c = s2.S2LatLng.from_degrees(38.0, -122.0) self.assertTrue(a == b) self.assertTrue(a != c) self.assertFalse(a != b) self.assertFalse(a == c) def test_comparison(self): a = s2.S2LatLng.from_degrees(10.0, 20.0) b = s2.S2LatLng.from_degrees(20.0, 10.0) self.assertTrue(a < b) self.assertTrue(b > a) self.assertTrue(a <= b) self.assertTrue(b >= a) self.assertTrue(a <= a) self.assertTrue(a >= a) def test_addition(self): a = s2.S2LatLng.from_degrees(10.0, 20.0) b = s2.S2LatLng.from_degrees(30.0, 40.0) result = a + b self.assertAlmostEqual(result.lat.degrees, 40.0) self.assertAlmostEqual(result.lng.degrees, 60.0) def test_addition_normalizes(self): # 80 + 20 = 100 degrees latitude, should clamp to 90. a = s2.S2LatLng.from_degrees(80.0, 170.0) b = s2.S2LatLng.from_degrees(20.0, 30.0) result = a + b self.assertAlmostEqual(result.lat.degrees, 90.0) # 170 + 30 = 200 degrees longitude, should wrap to -160. self.assertAlmostEqual(result.lng.degrees, -160.0) def test_subtraction(self): a = s2.S2LatLng.from_degrees(30.0, 40.0) b = s2.S2LatLng.from_degrees(10.0, 20.0) result = a - b self.assertAlmostEqual(result.lat.degrees, 20.0) self.assertAlmostEqual(result.lng.degrees, 20.0) def test_subtraction_normalizes(self): # -80 - 20 = -100 degrees latitude, should clamp to -90. a = s2.S2LatLng.from_degrees(-80.0, -170.0) b = s2.S2LatLng.from_degrees(20.0, 30.0) result = a - b self.assertAlmostEqual(result.lat.degrees, -90.0) # -170 - 30 = -200 degrees longitude, should wrap to 160. self.assertAlmostEqual(result.lng.degrees, 160.0) def test_scalar_multiplication(self): ll = s2.S2LatLng.from_degrees(10.0, 20.0) result1 = ll * 2.0 result2 = 2.0 * ll for result in [result1, result2]: self.assertAlmostEqual(result.lat.degrees, 20.0) self.assertAlmostEqual(result.lng.degrees, 40.0) def test_scalar_multiplication_inf_raises(self): ll = s2.S2LatLng.from_degrees(10.0, 20.0) with self.assertRaises(ValueError): ll * float("inf") def test_scalar_multiplication_nan_raises(self): ll = s2.S2LatLng.from_degrees(10.0, 20.0) with self.assertRaises(ValueError): ll * float("nan") def test_rmul_inf_raises(self): ll = s2.S2LatLng.from_degrees(10.0, 20.0) with self.assertRaises(ValueError): float("inf") * ll def test_scalar_multiplication_normalizes(self): ll = s2.S2LatLng.from_degrees(60.0, 120.0) result = ll * 2.0 # 120 degrees latitude -> clamped to 90 self.assertAlmostEqual(result.lat.degrees, 90.0) # 240 degrees longitude -> wrapped to -120 self.assertAlmostEqual(result.lng.degrees, -120.0) def test_hash(self): a = s2.S2LatLng.from_degrees(45.0, 90.0) b = s2.S2LatLng.from_degrees(45.0, 90.0) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_repr(self): ll = s2.S2LatLng.from_degrees(45.0, -90.0) self.assertEqual(repr(ll), "S2LatLng([45.0000000, -90.0000000])") def test_str(self): ll = s2.S2LatLng.from_degrees(45.0, -90.0) self.assertEqual(str(ll), "[45.0000000, -90.0000000]") def test_repr_zero(self): ll = s2.S2LatLng() self.assertEqual(repr(ll), "S2LatLng([0.0000000, 0.0000000])") if __name__ == "__main__": unittest.main() src/python/s2point_bindings.cc000066400000000000000000000067501524103652300167610ustar00rootroot00000000000000#include #include #include #include "absl/hash/hash.h" #include "s2/s2point.h" namespace py = pybind11; void bind_s2point(py::module& m) { py::class_(m, "S2Point") // Constructors .def(py::init<>(), "Default constructor creates a zero vector") .def(py::init(), py::arg("x"), py::arg("y"), py::arg("z"), "Constructor that accepts x, y, z coordinates") .def(py::init([](py::tuple t) { if (t.size() != 3) { throw py::value_error("Tuple must have exactly 3 elements"); } return S2Point(t[0].cast(), t[1].cast(), t[2].cast()); }), py::arg("coords"), "Constructor that accepts a tuple of (x, y, z) coordinates") // Properties .def_property_readonly("x", py::overload_cast<>(&S2Point::x, py::const_), "The x coordinate") .def_property_readonly("y", py::overload_cast<>(&S2Point::y, py::const_), "The y coordinate") .def_property_readonly("z", py::overload_cast<>(&S2Point::z, py::const_), "The z coordinate") .def("data", [](const S2Point& self) { return py::make_tuple(self.x(), self.y(), self.z()); }, "Return coordinates as a tuple (x, y, z)") // Vector operations .def("norm", &S2Point::Norm, "Return the Euclidean norm (length)") .def("norm2", &S2Point::Norm2, "Return the squared Euclidean norm (dot product with itself)") .def("normalize", &S2Point::Normalize, "Return a normalized copy of the vector.\n\n" "Returns a unit vector if the norm is nonzero.") .def("dot_prod", [](const S2Point& self, const S2Point& other) { return self.DotProd(other); }, py::arg("other"), "Return the dot product with another point") .def("cross_prod", [](const S2Point& self, const S2Point& other) -> S2Point { return self.CrossProd(other); }, py::arg("other"), "Return the cross product with another point") .def("angle", [](const S2Point& self, const S2Point& other) { return self.Angle(other); }, py::arg("other"), "Return the angle between this and another point (radians).\n\n" "The result is in the range [0, pi]. If either vector is zero-length,\n" "or nearly zero-length, the result will be zero.") // Operators .def(py::self + py::self, "Add two points (vector addition)") .def(py::self - py::self, "Subtract two points (vector subtraction)") .def(py::self * double(), "Multiply by scalar") .def("__rmul__", [](const S2Point& self, double v) -> S2Point { return self * v; }, "Multiply by scalar (reversed operands)") .def(py::self / double(), "Divide by scalar") .def(-py::self, "Negate point") .def(py::self == py::self, "Return true if points are exactly equal") .def(py::self != py::self, "Return true if points are not exactly equal") .def("__hash__", [](const S2Point& self) { return absl::HashOf(self); }) // String representation // __repr__ prefixes class name, __str__ delegates to C++ operator<< .def("__repr__", [](const S2Point& p) { std::ostringstream oss; oss << "S2Point(" << p << ")"; return oss.str(); }) .def("__str__", [](const S2Point& p) { std::ostringstream oss; oss << p; return oss.str(); }); } src/python/s2point_test.py000066400000000000000000000113451524103652300162020ustar00rootroot00000000000000"""Tests for S2Point pybind11 bindings.""" import math import unittest import s2geometry_pybind as s2 class TestS2Point(unittest.TestCase): """Test cases for S2Point bindings.""" # Constructors def test_default_constructor(self): p = s2.S2Point() self.assertEqual(p.x, 0.0) self.assertEqual(p.y, 0.0) self.assertEqual(p.z, 0.0) def test_constructor_with_coordinates(self): p = s2.S2Point(1.0, 2.0, 3.0) self.assertEqual(p.x, 1.0) self.assertEqual(p.y, 2.0) self.assertEqual(p.z, 3.0) def test_unnormalized_point(self): # Unnormalized points are accepted by the constructor. p = s2.S2Point(3.0, 4.0, 0.0) self.assertAlmostEqual(p.x, 3.0) self.assertAlmostEqual(p.y, 4.0) self.assertAlmostEqual(p.z, 0.0) self.assertAlmostEqual(p.norm(), 5.0) # Not on unit sphere # User may call normalize() to obtain a unit vector. normalized = p.normalize() self.assertAlmostEqual(normalized.norm(), 1.0) def test_constructor_from_tuple(self): p = s2.S2Point((1.0, 2.0, 3.0)) self.assertEqual(p.x, 1.0) self.assertEqual(p.y, 2.0) self.assertEqual(p.z, 3.0) def test_constructor_from_tuple_wrong_length(self): with self.assertRaises(ValueError): s2.S2Point((1.0, 2.0)) with self.assertRaises(ValueError): s2.S2Point((1.0, 2.0, 3.0, 4.0)) # Properties def test_data(self): p = s2.S2Point(1.0, 2.0, 3.0) coords = p.data() self.assertEqual(coords, (1.0, 2.0, 3.0)) # Vector operations def test_norm(self): p = s2.S2Point(3.0, 4.0, 0.0) self.assertAlmostEqual(p.norm(), 5.0) self.assertAlmostEqual(p.norm2(), 25.0) def test_normalize(self): p = s2.S2Point(3.0, 4.0, 0.0) normalized = p.normalize() self.assertAlmostEqual(normalized.norm(), 1.0) self.assertAlmostEqual(normalized.x, 0.6) self.assertAlmostEqual(normalized.y, 0.8) self.assertAlmostEqual(normalized.z, 0.0) def test_dot_product(self): p1 = s2.S2Point(1.0, 0.0, 0.0) p2 = s2.S2Point(0.0, 1.0, 0.0) p3 = s2.S2Point(1.0, 0.0, 0.0) self.assertAlmostEqual(p1.dot_prod(p2), 0.0) self.assertAlmostEqual(p1.dot_prod(p3), 1.0) def test_cross_product(self): p1 = s2.S2Point(1.0, 0.0, 0.0) p2 = s2.S2Point(0.0, 1.0, 0.0) cross = p1.cross_prod(p2) self.assertAlmostEqual(cross.x, 0.0) self.assertAlmostEqual(cross.y, 0.0) self.assertAlmostEqual(cross.z, 1.0) def test_angle(self): p1 = s2.S2Point(1.0, 0.0, 0.0) p2 = s2.S2Point(0.0, 1.0, 0.0) self.assertAlmostEqual(p1.angle(p2), math.pi / 2) # Operators def test_addition(self): p1 = s2.S2Point(1.0, 2.0, 3.0) p2 = s2.S2Point(4.0, 5.0, 6.0) result = p1 + p2 self.assertAlmostEqual(result.x, 5.0) self.assertAlmostEqual(result.y, 7.0) self.assertAlmostEqual(result.z, 9.0) def test_subtraction(self): p1 = s2.S2Point(4.0, 5.0, 6.0) p2 = s2.S2Point(1.0, 2.0, 3.0) result = p1 - p2 self.assertAlmostEqual(result.x, 3.0) self.assertAlmostEqual(result.y, 3.0) self.assertAlmostEqual(result.z, 3.0) def test_scalar_multiplication(self): p = s2.S2Point(1.0, 2.0, 3.0) result1 = p * 2.0 result2 = 2.0 * p for result in [result1, result2]: self.assertAlmostEqual(result.x, 2.0) self.assertAlmostEqual(result.y, 4.0) self.assertAlmostEqual(result.z, 6.0) def test_scalar_division(self): p = s2.S2Point(2.0, 4.0, 6.0) result = p / 2.0 self.assertAlmostEqual(result.x, 1.0) self.assertAlmostEqual(result.y, 2.0) self.assertAlmostEqual(result.z, 3.0) def test_negation(self): p = s2.S2Point(1.0, -2.0, 3.0) result = -p self.assertAlmostEqual(result.x, -1.0) self.assertAlmostEqual(result.y, 2.0) self.assertAlmostEqual(result.z, -3.0) def test_equality(self): p1 = s2.S2Point(1.0, 2.0, 3.0) p2 = s2.S2Point(1.0, 2.0, 3.0) p3 = s2.S2Point(1.0, 2.0, 4.0) self.assertEqual(p1, p2) self.assertNotEqual(p1, p3) def test_hash(self): a = s2.S2Point(1.0, 0.0, 0.0) b = s2.S2Point(1.0, 0.0, 0.0) self.assertEqual(hash(a), hash(b)) self.assertEqual(len({a, b}), 1) # String representation def test_string_representation(self): p = s2.S2Point(1.0, 2.0, 3.0) self.assertEqual(repr(p), "S2Point([1, 2, 3])") self.assertEqual(str(p), "[1, 2, 3]") if __name__ == "__main__": unittest.main() src/s2/000077500000000000000000000000001524103652300121725ustar00rootroot00000000000000src/s2/_fp_contract_off.h000066400000000000000000000044351524103652300156440ustar00rootroot00000000000000// Copyright 2015 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2__FP_CONTRACT_OFF_H_ #define S2__FP_CONTRACT_OFF_H_ // Turn off the fused multiply-add optimization ("fp-contract"). With // fp-contract on, any expression of the form "a * b + c" has two possible // results, and the compiler is free to choose either of them. Effectively // this makes it impossible to write deterministic functions that involve // floating-point math. // // S2 requires deterministic arithmetic for correctness. We need to turn off // fp-contract for the entire compilation unit, because S2 has public inline // functions, and the optimization is controlled by the setting in effect when // inline functions are instantiated (not when they are defined). // // Note that there is a standard C pragma to turn off FP contraction: // #pragma STDC FP_CONTRACT OFF // but it is not implemented in GCC because the standard pragma allows control // at the level of compound statements rather than entire functions. // // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=20785 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=37845 // // This file may be included with other files in any order, as long as it // appears before the first non-inline function definition. It is // named with an underscore so that it is included first among the S2 headers. #if defined(__GNUC__) && !defined(__clang__) // GCC defines its own pragma that operates at the function level rather than // the statement level. #pragma GCC optimize("fp-contract=off") #else // Assume all other compilers support or ignore the standard pragma. // Avoid gcc `-Wunknown-pragmas` warnings by not using this for gcc. #pragma STDC FP_CONTRACT OFF #endif #endif // S2__FP_CONTRACT_OFF_H_ src/s2/base/000077500000000000000000000000001524103652300131045ustar00rootroot00000000000000src/s2/base/BUILD.bazel000066400000000000000000000013361524103652300147650ustar00rootroot00000000000000load("@rules_cc//cc:defs.bzl", "cc_library") package(default_visibility = ["//:__subpackages__"]) cc_library( name = "casts", hdrs = ["casts.h"], deps = [ "@abseil-cpp//absl/base:config", ], ) cc_library( name = "log_severity", hdrs = ["log_severity.h"], deps = [ "@abseil-cpp//absl/base:log_severity", ], ) cc_library( name = "malloc_extension", srcs = ["malloc_extension.cc"], hdrs = ["malloc_extension.h"], deps = [ "@abseil-cpp//absl/base:core_headers", ], ) cc_library( name = "spinlock", hdrs = ["spinlock.h"], deps = [ "@abseil-cpp//absl/base:core_headers", ], ) cc_library( name = "timer", hdrs = ["timer.h"], ) src/s2/base/casts.h000066400000000000000000000041331524103652300143730ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_BASE_CASTS_H_ #define S2_BASE_CASTS_H_ #include #include #include "absl/base/config.h" template inline To down_cast(From* f) { static_assert((std::is_base_of>::value), "target type not derived from source type"); // We depend on abseil-cpp internals, but if this doesn't get defined, // we will just not have the assert. #if ABSL_INTERNAL_HAS_RTTI assert(f == nullptr || dynamic_cast(f) != nullptr); #endif return static_cast(f); } // Overload of down_cast for references. Use like this: down_cast(foo). // The code is slightly convoluted because we're still using the pointer // form of dynamic cast. (The reference form throws an exception if it // fails.) // // There's no need for a special const overload either for the pointer // or the reference form. If you call down_cast with a const T&, the // compiler will just bind From to const T. template inline To down_cast(From& f) { static_assert(std::is_lvalue_reference::value, "target type not a reference"); static_assert((std::is_base_of>::value), "target type not derived from source type"); // We skip the assert and hence the dynamic_cast if RTTI is disabled. #if ABSL_INTERNAL_HAS_RTTI assert(dynamic_cast*>(&f) != nullptr); #endif return static_cast(f); } #endif // S2_BASE_CASTS_H_ src/s2/base/log_severity.h000066400000000000000000000015201524103652300157660ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_BASE_LOG_SEVERITY_H_ #define S2_BASE_LOG_SEVERITY_H_ #include "absl/base/log_severity.h" #ifdef NDEBUG constexpr bool S2_DEBUG_MODE = false; #else constexpr bool S2_DEBUG_MODE = true; #endif #endif // S2_BASE_LOG_SEVERITY_H_ src/s2/base/malloc_extension.cc000066400000000000000000000017711524103652300167640ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/base/malloc_extension.h" #include #include #include "absl/base/attributes.h" ABSL_ATTRIBUTE_WEAK ABSL_ATTRIBUTE_NOINLINE size_t nallocx(size_t size, int) noexcept { return size; } ABSL_ATTRIBUTE_WEAK ABSL_ATTRIBUTE_NOINLINE __sized_ptr_t __size_returning_new(size_t size) { return {::operator new(size), size}; } src/s2/base/malloc_extension.h000066400000000000000000000032471524103652300166260ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_BASE_MALLOC_EXTENSION_H_ #define S2_BASE_MALLOC_EXTENSION_H_ // Some s2geometry functions use TCMalloc extensions. Here, we provide // default implementations so s2geometry can be used with other allocators. // // See // https://github.com/google/tcmalloc/blob/master/tcmalloc/malloc_extension.h #include extern "C" { // `nallocx` performs the same size computation that `malloc` would perform. // The default weak implementation just returns the `size` argument. // See https://jemalloc.net/jemalloc.3.html size_t nallocx(size_t size, int flags) noexcept; // `__size_returning_new` returns a pointer to the allocated memory along // with the (possibly rounded up) actual allocation size used. The default // weak implementation just returns the requested size. // This is a TCMalloc prototype of P0901R5 "Size feedback in operator new". // https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0901r5.html struct __sized_ptr_t { void* p; size_t n; }; __sized_ptr_t __size_returning_new(size_t size); } // extern "C" #endif // S2_BASE_MALLOC_EXTENSION_H_ src/s2/base/spinlock.h000066400000000000000000000033611524103652300151020ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_BASE_SPINLOCK_H_ #define S2_BASE_SPINLOCK_H_ #include #include "absl/base/thread_annotations.h" class ABSL_LOCKABLE ABSL_ATTRIBUTE_WARN_UNUSED SpinLock { public: SpinLock() = default; ~SpinLock() = default; SpinLock(SpinLock const&) = delete; SpinLock& operator=(SpinLock const&) = delete; inline void lock() ABSL_EXCLUSIVE_LOCK_FUNCTION() { while (locked_.exchange(true, std::memory_order_acquire)) { // Spin. continue; } } inline void unlock() ABSL_UNLOCK_FUNCTION() { locked_.store(false, std::memory_order_release); } [[nodiscard]] inline bool IsHeld() const { return locked_.load(std::memory_order_relaxed); } private: std::atomic_bool locked_{false}; }; class [[nodiscard]] ABSL_SCOPED_LOCKABLE SpinLockHolder { public: inline explicit SpinLockHolder(SpinLock& l) ABSL_EXCLUSIVE_LOCK_FUNCTION(l) : lock_(l) { l.lock(); } inline ~SpinLockHolder() ABSL_UNLOCK_FUNCTION() { lock_.unlock(); } SpinLockHolder(const SpinLockHolder&) = delete; SpinLockHolder& operator=(const SpinLockHolder&) = delete; private: SpinLock& lock_; }; #endif // S2_BASE_SPINLOCK_H_ src/s2/base/timer.h000066400000000000000000000022571524103652300144030ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_BASE_TIMER_H_ #define S2_BASE_TIMER_H_ #include #include class CycleTimer { public: CycleTimer() = default; void Start() { start_ = Now(); } int64_t GetInMs() const { using msec = std::chrono::milliseconds; return std::chrono::duration_cast(GetDuration()).count(); } private: using Clock = std::chrono::high_resolution_clock; static Clock::time_point Now() { return Clock::now(); } Clock::duration GetDuration() const { return Now() - start_; } Clock::time_point start_; }; #endif // S2_BASE_TIMER_H_ src/s2/encoded_s2cell_id_vector.cc000066400000000000000000000157451524103652300174200ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_s2cell_id_vector.h" #include #include #include #include "absl/log/absl_check.h" #include "absl/numeric/bits.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/encoded_uint_vector.h" #include "s2/s2cell_id.h" using absl::Span; using std::max; using std::min; using std::vector; namespace s2coding { void EncodeBaseShift(Encoder* encoder, int shift, uint64_t base, int base_len) { encoder->Ensure(2 + base_len); // "shift" and "base_len" are encoded in 1 or 2 bytes. // // "shift_code" is 5 bits: // values <= 28 represent even shifts in the range 0..56 // values 29, 30 represent odd shifts 1 and 3 // value 31 indicates that the shift is odd and encoded in the next byte int shift_code = shift >> 1; if (shift & 1) { shift_code = min(31, shift_code + 29); } encoder->put8((shift_code << 3) | base_len); if (shift_code == 31) { encoder->put8(shift >> 1); // Shift is always odd, so 3 bits unused. } // Encode the "base_len" most-significant bytes of "base". uint64_t base_bytes = base >> (64 - 8 * max(1, base_len)); EncodeUintWithLength(base_bytes, base_len, encoder); } void EncodeS2CellIdVector(Span v, Encoder* encoder) { // v[i] is encoded as (base + (deltas[i] << shift)). // // "base" consists of 0-7 bytes, and is always shifted so that its bytes are // the most-significant bytes of a uint64_t. // // "deltas" is an EncodedUintVector, which means that all deltas // have a fixed-length encoding determined by the largest delta. // // "shift" is in the range 0..56. The shift value is odd only if all // S2CellIds are at the same level, in which case the bit at position // (shift - 1) is automatically set to 1 in "base". // // "base" (3 bits) and "shift" (6 bits) are encoded in either one or two // bytes as follows: // // - if (shift <= 4 or shift is even), then 1 byte // - otherwise 2 bytes // // Note that (shift == 1) means that all S2CellIds are leaf cells, and // (shift == 2) means that all S2CellIds are at level 29. // // The full encoded format is as follows: // // Byte 0, bits 0-2: base length (0-7 bytes) // Byte 0, bits 3-7: encoded shift (see below) // Byte 1: extended shift code (only needed for odd shifts >= 5) // Followed by 0-7 bytes of "base" // Followed by an EncodedUintVector of deltas. uint64_t v_or = 0, v_and = ~0ULL, v_min = ~0ULL, v_max = 0; for (auto cellid : v) { v_or |= cellid.id(); v_and &= cellid.id(); v_min = min(v_min, cellid.id()); v_max = max(v_max, cellid.id()); } // These variables represent the values that will used during encoding. uint64_t e_base = 0; // Base value. int e_base_len = 0; // Number of bytes to represent "base". int e_shift = 0; // Delta shift. int e_max_delta_msb = 0; // Bit position of the MSB of the largest delta. if (v_or > 0) { // We only allow even shifts, unless all values have the same low bit (in // which case the shift is odd and the preceding bit is implicitly on). // There is no point in allowing shifts > 56 since deltas are encoded in // at least 1 byte each. e_shift = min(56, absl::countr_zero(v_or) & ~1); if (v_and & (1ULL << e_shift)) ++e_shift; // All S2CellIds same level. // "base" consists of the "base_len" most significant bytes of the minimum // S2CellId. We consider all possible values of "base_len" (0..7) and // choose the one that minimizes the total encoding size. uint64_t e_bytes = ~0ULL; // Best encoding size so far. for (int len = 0; len < 8; ++len) { // "t_base" is the base value being tested (first "len" bytes of v_min). // "t_max_delta_msb" is the most-significant bit position (i.e. bit-width // minus one) of the largest delta (or zero if there are no deltas, i.e. // if v.size() == 0). "t_bytes" is the total size of the variable // portion of the encoding. uint64_t t_base = v_min & ~(~0ULL >> (8 * len)); int t_max_delta_msb = max( 0, static_cast(absl::bit_width((v_max - t_base) >> e_shift)) - 1); uint64_t t_bytes = len + v.size() * ((t_max_delta_msb >> 3) + 1); if (t_bytes < e_bytes) { e_base = t_base; e_base_len = len; e_max_delta_msb = t_max_delta_msb; e_bytes = t_bytes; } } // It takes one extra byte to encode odd shifts (i.e., the case where all // S2CellIds are at the same level), so check whether we can get the same // encoding size per delta using an even shift. if ((e_shift & 1) && (e_max_delta_msb & 7) != 7) --e_shift; } ABSL_DCHECK_LE(e_base_len, 7); ABSL_DCHECK_LE(e_shift, 56); EncodeBaseShift(encoder, e_shift, e_base, e_base_len); // Finally, encode the vector of deltas. vector deltas; deltas.reserve(v.size()); for (auto cellid : v) { deltas.push_back((cellid.id() - e_base) >> e_shift); } EncodeUintVector(deltas, encoder); } bool EncodedS2CellIdVector::Init(Decoder* decoder) { // All encodings have at least 2 bytes (one for our header and one for the // EncodedUintVector header), so this is safe. if (decoder->avail() < 2) return false; // Invert the encoding of (shift_code, base_len) described above. int code_plus_len = decoder->get8(); int shift_code = code_plus_len >> 3; if (shift_code == 31) { shift_code = 29 + decoder->get8(); if (shift_code > 56) return false; // Valid range 0..56 } // Decode the "base_len" most-significant bytes of "base". base_len_ = code_plus_len & 7; if (!DecodeUintWithLength(base_len_, decoder, &base_)) return false; base_ <<= 64 - 8 * max(1, (int)base_len_); // Invert the encoding of "shift_code" described above. if (shift_code >= 29) { shift_ = 2 * (shift_code - 29) + 1; base_ |= 1ULL << (shift_ - 1); } else { shift_ = 2 * shift_code; } return deltas_.Init(decoder); } vector EncodedS2CellIdVector::Decode() const { vector result(size()); for (size_t i = 0; i < size(); ++i) { result[i] = (*this)[i]; } return result; } void EncodedS2CellIdVector::Encode(Encoder* encoder) const { // Re-encode the base and shift values. EncodeBaseShift(encoder, shift_, base_, base_len_); // And copy the encoded deltas. deltas_.Encode(encoder); } } // namespace s2coding src/s2/encoded_s2cell_id_vector.h000066400000000000000000000103621524103652300172500ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_ENCODED_S2CELL_ID_VECTOR_H_ #define S2_ENCODED_S2CELL_ID_VECTOR_H_ #include #include #include #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/encoded_uint_vector.h" #include "s2/s2cell_id.h" namespace s2coding { // Encodes a vector of S2CellIds in a format that can later be decoded as an // EncodedS2CellIdVector. The S2CellIds do not need to be valid. // // REQUIRES: "encoder" uses the default constructor, so that its buffer // can be enlarged as necessary by calling Ensure(int). void EncodeS2CellIdVector(absl::Span v, Encoder* encoder); // This class represents an encoded vector of S2CellIds. Values are decoded // only when they are accessed. This allows for very fast initialization and // no additional memory use beyond the encoded data. The encoded data is not // owned by this class; typically it points into a large contiguous buffer // that contains other encoded data as well. // // This is one of several helper classes that allow complex data structures to // be initialized from an encoded format in constant time and then decoded on // demand. This can be a big performance advantage when only a small part of // the data structure is actually used. // // The S2CellIds do not need to be sorted or at the same level. The // implementation is biased towards minimizing decoding times rather than // space usage. // // NOTE: If your S2CellIds represent S2Points that have been snapped to // S2CellId centers, then EncodedS2PointVector is both faster and smaller. class EncodedS2CellIdVector { public: // Constructs an uninitialized object; requires Init() to be called. EncodedS2CellIdVector() = default; // Initializes the EncodedS2CellIdVector. // // REQUIRES: The Decoder data buffer must outlive this object. bool Init(Decoder* decoder); // Returns the size of the original vector. size_t size() const; // Returns the element at the given index. S2CellId operator[](int i) const; // Returns the index of the first element x such that (x >= target), or // size() if no such element exists. // // REQUIRES: The vector elements are sorted in non-decreasing order. size_t lower_bound(S2CellId target) const; // Decodes and returns the entire original vector. std::vector Decode() const; // Copies the encoded byte stream to a new encoder. void Encode(Encoder* encoder) const; private: // Values are decoded as (base_ + (deltas_[i] << shift_)). EncodedUintVector deltas_; uint64_t base_; uint8_t shift_; uint8_t base_len_; }; ////////////////// Implementation details follow //////////////////// inline size_t EncodedS2CellIdVector::size() const { return deltas_.size(); } inline S2CellId EncodedS2CellIdVector::operator[](int i) const { return S2CellId((deltas_[i] << shift_) + base_); } inline size_t EncodedS2CellIdVector::lower_bound(S2CellId target) const { // We optimize the search by converting "target" to the corresponding delta // value and then searching directly in the deltas_ vector. // // To invert operator[], we essentially compute ((target - base_) >> shift_) // except that we also need to round up when shifting. The first two cases // ensure that "target" doesn't wrap around past zero when we do this. if (target.id() <= base_) return 0; if (target >= S2CellId::End(S2CellId::kMaxLevel)) return size(); return deltas_.lower_bound( (target.id() - base_ + (uint64_t{1} << shift_) - 1) >> shift_); } } // namespace s2coding #endif // S2_ENCODED_S2CELL_ID_VECTOR_H_ src/s2/encoded_s2cell_id_vector_test.cc000066400000000000000000000254571524103652300204600ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_s2cell_id_vector.h" #include #include #include #include #include #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/mutable_s2shape_index.h" #include "s2/s1angle.h" #include "s2/s2cell_id.h" #include "s2/s2fractal.h" #include "s2/s2loop.h" #include "s2/s2point.h" #include "s2/s2pointutil.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" using s2textformat::MakeCellIdOrDie; using std::make_unique; using std::vector; namespace s2coding { namespace { // Encodes the given vector and returns the corresponding // EncodedS2CellIdVector (which points into the Encoder's data buffer). EncodedS2CellIdVector MakeEncodedS2CellIdVector( absl::Span input, Encoder* encoder) { EncodeS2CellIdVector(input, encoder); Decoder decoder(encoder->base(), encoder->length()); EncodedS2CellIdVector cell_ids; EXPECT_TRUE(cell_ids.Init(&decoder)); return cell_ids; } // Encodes the given vector and checks that it has the expected size and // contents. void TestEncodedS2CellIdVector(const vector& expected, size_t expected_bytes) { Encoder encoder; EncodedS2CellIdVector actual = MakeEncodedS2CellIdVector(expected, &encoder); EXPECT_EQ(expected_bytes, encoder.length()); EXPECT_EQ(actual.Decode(), expected); } // Like the above, but accepts a vector rather than a // vector. void TestEncodedS2CellIdVector(absl::Span raw_expected, size_t expected_bytes) { vector expected; for (uint64_t raw_id : raw_expected) { expected.push_back(S2CellId(raw_id)); } TestEncodedS2CellIdVector(expected, expected_bytes); } TEST(EncodedS2CellIdVector, Empty) { TestEncodedS2CellIdVector(vector{}, 2); } TEST(EncodedS2CellIdVector, None) { TestEncodedS2CellIdVector({S2CellId::None()}, 3); } TEST(EncodedS2CellIdVector, NoneNone) { TestEncodedS2CellIdVector({S2CellId::None(), S2CellId::None()}, 4); } TEST(EncodedS2CellIdVector, Sentinel) { TestEncodedS2CellIdVector({S2CellId::Sentinel()}, 10); } TEST(EncodedS2CellIdVector, MaximumShiftCell) { // Tests the encoding of a single cell at level 2, which corresponds the // maximum encodable shift value (56). TestEncodedS2CellIdVector({MakeCellIdOrDie("0/00")}, 3); } TEST(EncodedS2CellIdVector, SentinelSentinel) { TestEncodedS2CellIdVector({S2CellId::Sentinel(), S2CellId::Sentinel()}, 11); } TEST(EncodedS2CellIdVector, NoneSentinelNone) { TestEncodedS2CellIdVector( {S2CellId::None(), S2CellId::Sentinel(), S2CellId::None()}, 26); } TEST(EncodedS2CellIdVector, InvalidCells) { // Tests that cells with an invalid LSB can be encoded. TestEncodedS2CellIdVector({0x6, 0xe, 0x7e}, 5); } TEST(EncodedS2CellIdVector, OneByteLeafCells) { // Tests that (1) if all cells are leaf cells, the low bit is not encoded, // and (2) this can be indicated using the standard 1-byte header. TestEncodedS2CellIdVector({0x3, 0x7, 0x177}, 5); } TEST(EncodedS2CellIdVector, OneByteLevel29Cells) { // Tests that (1) if all cells are at level 29, the low bit is not encoded, // and (2) this can be indicated using the standard 1-byte header. TestEncodedS2CellIdVector({0xc, 0x1c, 0x47c}, 5); } TEST(EncodedS2CellIdVector, OneByteLevel28Cells) { // Tests that (1) if all cells are at level 28, the low bit is not encoded, // and (2) this can be indicated using the extended 2-byte header. TestEncodedS2CellIdVector({0x30, 0x70, 0x1770}, 6); } TEST(EncodedS2CellIdVector, OneByteMixedCellLevels) { // Tests that cells at mixed levels can be encoded in one byte. TestEncodedS2CellIdVector({0x300, 0x1c00, 0x7000, 0xff00}, 6); } TEST(EncodedS2CellIdVector, OneByteMixedCellLevelsWithPrefix) { // Tests that cells at mixed levels can be encoded in one byte even when // they share a multi-byte prefix. TestEncodedS2CellIdVector({ 0x1234567800000300, 0x1234567800001c00, 0x1234567800007000, 0x123456780000ff00}, 10); } TEST(EncodedS2CellIdVector, OneByteRangeWithBaseValue) { // Tests that cells can be encoded in one byte by choosing a base value // whose bit range overlaps the delta values. // 1 byte header, 3 bytes base, 1 byte size, 4 bytes deltas TestEncodedS2CellIdVector({ 0x00ffff0000000000, 0x0100fc0000000000, 0x0100500000000000, 0x0100330000000000}, 9); } TEST(EncodedS2CellIdVector, MaxShiftRange) { const vector bytes = { (31 << 3) // 31 -> add 29 to bytes[1]. + 1, // Number of encoded cell IDs. 27, // 27+29 is the maximum supported shift. 1, 0 // Encoded cell ID. Not important. }; Decoder decoder(bytes.data(), bytes.size()); EncodedS2CellIdVector cell_ids; EXPECT_TRUE(cell_ids.Init(&decoder)); } TEST(EncodedS2CellIdVector, ShiftOutOfRange) { const vector bytes = { (31 << 3) // 31 -> add 29 to bytes[1]. + 1, // Number of encoded cell IDs. 28, // 28+29 is greater than the maximum supported shift of 56. 1, 0 // Encoded cell ID. Not important. }; Decoder decoder(bytes.data(), bytes.size()); EncodedS2CellIdVector cell_ids; EXPECT_FALSE(cell_ids.Init(&decoder)); } TEST(EncodedS2CellIdVector, SixFaceCells) { vector ids; for (int face = 0; face < 6; ++face) { ids.push_back(S2CellId::FromFace(face)); } TestEncodedS2CellIdVector(ids, 8); } TEST(EncodedS2CellIdVector, FourLevel10Children) { vector ids; S2CellId parent = MakeCellIdOrDie("3/012301230"); for (S2CellId id = parent.child_begin(); id != parent.child_end(); id = id.next()) { ids.push_back(id); } TestEncodedS2CellIdVector(ids, 8); } TEST(EncodedS2CellIdVector, FractalS2ShapeIndexCells) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "FRACTAL_S2_SHAPE_INDEX_CELLS", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); S2Fractal fractal(bitgen); fractal.SetLevelForApproxMaxEdges(3 * 1024); S2Point center = s2textformat::MakePointOrDie("47.677:-122.206"); MutableS2ShapeIndex index; index.Add(make_unique( fractal.MakeLoop(S2::GetFrame(center), S1Angle::Degrees(1)))); vector ids; for (MutableS2ShapeIndex::Iterator it(&index, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { ids.push_back(it.id()); } EXPECT_EQ(966, ids.size()); TestEncodedS2CellIdVector(ids, 2902); } TEST(EncodedS2CellIdVector, CoveringCells) { vector ids{ 0x414a617f00000000, 0x414a61c000000000, 0x414a624000000000, 0x414a63c000000000, 0x414a647000000000, 0x414a64c000000000, 0x414a653000000000, 0x414a704000000000, 0x414a70c000000000, 0x414a714000000000, 0x414a71b000000000, 0x414a7a7c00000000, 0x414a7ac000000000, 0x414a8a4000000000, 0x414a8bc000000000, 0x414a8c4000000000, 0x414a8d7000000000, 0x414a8dc000000000, 0x414a914000000000, 0x414a91c000000000, 0x414a924000000000, 0x414a942c00000000, 0x414a95c000000000, 0x414a96c000000000, 0x414ab0c000000000, 0x414ab14000000000, 0x414ab34000000000, 0x414ab3c000000000, 0x414ab44000000000, 0x414ab4c000000000, 0x414ab6c000000000, 0x414ab74000000000, 0x414ab8c000000000, 0x414ab94000000000, 0x414aba1000000000, 0x414aba3000000000, 0x414abbc000000000, 0x414abe4000000000, 0x414abec000000000, 0x414abf4000000000, 0x46b5454000000000, 0x46b545c000000000, 0x46b5464000000000, 0x46b547c000000000, 0x46b5487000000000, 0x46b548c000000000, 0x46b5494000000000, 0x46b54a5400000000, 0x46b54ac000000000, 0x46b54b4000000000, 0x46b54bc000000000, 0x46b54c7000000000, 0x46b54c8004000000, 0x46b54ec000000000, 0x46b55ad400000000, 0x46b55b4000000000, 0x46b55bc000000000, 0x46b55c4000000000, 0x46b55c8100000000, 0x46b55dc000000000, 0x46b55e4000000000, 0x46b5604000000000, 0x46b560c000000000, 0x46b561c000000000, 0x46ca424000000000, 0x46ca42c000000000, 0x46ca43c000000000, 0x46ca444000000000, 0x46ca45c000000000, 0x46ca467000000000, 0x46ca469000000000, 0x46ca5fc000000000, 0x46ca604000000000, 0x46ca60c000000000, 0x46ca674000000000, 0x46ca679000000000, 0x46ca67f000000000, 0x46ca684000000000, 0x46ca855000000000, 0x46ca8c4000000000, 0x46ca8cc000000000, 0x46ca8e5400000000, 0x46ca8ec000000000, 0x46ca8f0100000000, 0x46ca8fc000000000, 0x46ca900400000000, 0x46ca98c000000000, 0x46ca994000000000, 0x46ca99c000000000, 0x46ca9a4000000000, 0x46ca9ac000000000, 0x46ca9bd500000000, 0x46ca9e4000000000, 0x46ca9ec000000000, 0x46caf34000000000, 0x46caf4c000000000, 0x46caf54000000000}; EXPECT_EQ(97, ids.size()); TestEncodedS2CellIdVector(ids, 488); } TEST(EncodedS2CellIdVector, LowerBoundLimits) { // Test seeking before the beginning and past the end of the vector. S2CellId first = S2CellId::Begin(S2CellId::kMaxLevel); S2CellId last = S2CellId::End(S2CellId::kMaxLevel).prev(); Encoder encoder; EncodedS2CellIdVector cell_ids = MakeEncodedS2CellIdVector( {first, last}, &encoder); EXPECT_EQ(0, cell_ids.lower_bound(S2CellId::None())); EXPECT_EQ(0, cell_ids.lower_bound(first)); EXPECT_EQ(1, cell_ids.lower_bound(first.next())); EXPECT_EQ(1, cell_ids.lower_bound(last.prev())); EXPECT_EQ(1, cell_ids.lower_bound(last)); EXPECT_EQ(2, cell_ids.lower_bound(last.next())); EXPECT_EQ(2, cell_ids.lower_bound(S2CellId::Sentinel())); } void EncodedS2CellIdVectorInitNeverCrashes(const vector& bytes, const uint64_t lower_bound) { Decoder decoder(bytes.data(), bytes.size()); EncodedS2CellIdVector cell_ids; if (!cell_ids.Init(&decoder)) { return; } const S2CellId cell_id(lower_bound); if (!cell_id.is_valid()) { return; } cell_ids.lower_bound(cell_id); } TEST(EncodedS2CellIdVector, EncodedS2CellIdVectorInitNeverCrashesRegression) { // This would overflow the size_ * len_ check in EncodedUintVector and let it // erroneously proceed to decoding, causing a segfault. EncodedS2CellIdVectorInitNeverCrashes( {32, 135, 128, 128, 128, 48, 39, 132, 143, 84}, 7059594055645134713 ); } } // namespace } // namespace s2coding src/s2/encoded_s2point_vector.cc000066400000000000000000001160271524103652300171510ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_s2point_vector.h" #include #include #include #include #include #include "absl/base/optimization.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/numeric/bits.h" #include "absl/strings/string_view.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/util/coding/varint.h" #include "s2/encoded_string_vector.h" #include "s2/encoded_uint_vector.h" #include "s2/s2cell_id.h" #include "s2/s2coder.h" #include "s2/s2coords.h" #include "s2/s2error.h" #include "s2/s2point.h" using absl::MakeSpan; using absl::Span; using std::max; using std::min; using std::vector; namespace s2coding { // Like util_bits::InterleaveUint32, but interleaves bit pairs rather than // individual bits. This format is faster to decode than the fully interleaved // format, and produces the same results for our use case. inline uint64_t InterleaveUint32BitPairs(const uint32_t val0, const uint32_t val1) { uint64_t v0 = val0, v1 = val1; v0 = (v0 | (v0 << 16)) & 0x0000ffff0000ffff; v1 = (v1 | (v1 << 16)) & 0x0000ffff0000ffff; v0 = (v0 | (v0 << 8)) & 0x00ff00ff00ff00ff; v1 = (v1 | (v1 << 8)) & 0x00ff00ff00ff00ff; v0 = (v0 | (v0 << 4)) & 0x0f0f0f0f0f0f0f0f; v1 = (v1 | (v1 << 4)) & 0x0f0f0f0f0f0f0f0f; v0 = (v0 | (v0 << 2)) & 0x3333333333333333; v1 = (v1 | (v1 << 2)) & 0x3333333333333333; return v0 | (v1 << 2); } // This code is about 50% faster than util_bits::DeinterleaveUint32, which // uses a lookup table. The speed advantage is expected to be even larger in // code that mixes bit interleaving with other significant operations since it // doesn't require keeping a 256-byte lookup table in the L1 data cache. inline void DeinterleaveUint32BitPairs(uint64_t code, uint32_t* val0, uint32_t* val1) { uint64_t v0 = code, v1 = code >> 2; v0 &= 0x3333333333333333; v0 |= v0 >> 2; v1 &= 0x3333333333333333; v1 |= v1 >> 2; v0 &= 0x0f0f0f0f0f0f0f0f; v0 |= v0 >> 4; v1 &= 0x0f0f0f0f0f0f0f0f; v1 |= v1 >> 4; v0 &= 0x00ff00ff00ff00ff; v0 |= v0 >> 8; v1 &= 0x00ff00ff00ff00ff; v1 |= v1 >> 8; v0 &= 0x0000ffff0000ffff; v0 |= v0 >> 16; v1 &= 0x0000ffff0000ffff; v1 |= v1 >> 16; *val0 = v0; *val1 = v1; } // Forward declarations. void EncodeS2PointVectorFast(Span points, Encoder* encoder); void EncodeS2PointVectorCompact(Span points, Encoder* encoder); // To save space (especially for vectors of length 0, 1, and 2), the encoding // format is encoded in the low-order 3 bits of the vector size. Up to 7 // encoding formats are supported (only 2 are currently defined). Additional // formats could be supported by using "7" as an overflow indicator and // encoding the actual format separately, but it seems unlikely we will ever // need to do that. static const int kEncodingFormatBits = 3; static const uint8_t kEncodingFormatMask = (1 << kEncodingFormatBits) - 1; void EncodeS2PointVector(Span points, CodingHint hint, Encoder* encoder) { switch (hint) { case CodingHint::FAST: return EncodeS2PointVectorFast(points, encoder); case CodingHint::COMPACT: return EncodeS2PointVectorCompact(points, encoder); default: ABSL_LOG(DFATAL) << "Unknown CodingHint: " << static_cast(hint); } } bool EncodedS2PointVector::Init(Decoder* decoder) { if (decoder->avail() < 1) return false; // Peek at the format but don't advance the decoder; the format-specific // Init functions will do that. format_ = static_cast(*decoder->skip(0) & kEncodingFormatMask); switch (format_) { case UNCOMPRESSED: return InitUncompressedFormat(decoder); case CELL_IDS: return InitCellIdsFormat(decoder); default: return false; } } bool EncodedS2PointVector::Init(Decoder* decoder, S2Error& error) { if (!Init(decoder)) { error = S2Error::DataLoss("Error initializing EncodedS2PointVector"); return false; } return true; } vector EncodedS2PointVector::Decode() const { vector points; points.reserve(size_); for (size_t i = 0; i < size_; ++i) { points.push_back((*this)[i]); } return points; } bool EncodedS2PointVector::Decode(absl::Span points) const { ABSL_DCHECK_EQ(points.size(), size()); for (size_t i = 0; i < size_; ++i) { points[i] = (*this)[i]; } return true; } std::vector EncodedS2PointVector::Decode(S2Error& error) const { vector points; points.reserve(size_); for (size_t i = 0; i < size_ && error.ok(); ++i) { points.push_back(At(i, error)); } return points; } bool EncodedS2PointVector::Decode(absl::Span points, S2Error& error) const { ABSL_DCHECK_EQ(points.size(), size()); for (size_t i = 0; i < size_ && error.ok(); ++i) { points[i] = At(i, error); } return error.ok(); } // The encoding must be identical to EncodeS2PointVector(). void EncodedS2PointVector::Encode(Encoder* encoder) const { switch (format_) { case UNCOMPRESSED: EncodeS2PointVectorFast(MakeSpan(uncompressed_.points, size_), encoder); break; case CELL_IDS: { // This is a full decode/encode dance, and not at all efficient. EncodeS2PointVectorCompact(Decode(), encoder); break; } default: ABSL_LOG(FATAL) << "Unknown Format: " << static_cast(format_); } } ////////////////////////////////////////////////////////////////////////////// // UNCOMPRESSED Encoding Format ////////////////////////////////////////////////////////////////////////////// // Encodes a vector of points, optimizing for (encoding and decoding) speed. void EncodeS2PointVectorFast(Span points, Encoder* encoder) { if constexpr (absl::endian::native != absl::endian::little) { ABSL_LOG(FATAL) << "Not implemented on big-endian architectures"; } // This function always uses the UNCOMPRESSED encoding. The header consists // of a varint64 in the following format: // // bits 0-2: encoding format (UNCOMPRESSED) // bits 3-63: vector size // // This is followed by an array of S2Points in little-endian order. encoder->Ensure(Varint::kMax64 + points.size() * sizeof(S2Point)); uint64_t size_format = (points.size() << kEncodingFormatBits | EncodedS2PointVector::UNCOMPRESSED); encoder->put_varint64(size_format); encoder->putn(points.data(), points.size() * sizeof(S2Point)); } bool EncodedS2PointVector::InitUncompressedFormat(Decoder* decoder) { #ifdef __arm__ constexpr bool kIsArm32 = true; #else constexpr bool kIsArm32 = false; #endif if constexpr (absl::endian::native != absl::endian::little || kIsArm32) { // TODO(b/231674214): Make this work on platforms that don't support // unaligned 64-bit little-endian reads, e.g. by falling back to // // bit_cast(LittleEndian::Load64()). // // Maybe the compiler is smart enough that we can do this all the time, // but more likely we will need two cases using the #ifdef above. // (Note that even ARMv7 does not support unaligned 64-bit loads.) ABSL_LOG(DFATAL) << "Needs architecture with 64-bit little-endian unaligned loads"; return false; } uint64_t size; if (!decoder->get_varint64(&size)) return false; size >>= kEncodingFormatBits; // Note that the encoding format supports up to 2**59 vertices, but we // currently only support decoding up to 2**31 vertices, as // `EncodedS2PointVectorShape::num_points()` returns `int`. if (size > std::numeric_limits::max()) return false; size_ = size; size_t bytes = size_t{size_} * sizeof(S2Point); if (decoder->avail() < bytes) return false; uncompressed_.points = reinterpret_cast(decoder->skip(0)); decoder->skip(bytes); return true; } ////////////////////////////////////////////////////////////////////////////// // CELL_IDS Encoding Format ////////////////////////////////////////////////////////////////////////////// // Represents a point that can be encoded as an S2CellId center. // (If such an encoding is not possible then level < 0.) struct CellPoint { // Constructor necessary in order to narrow "int" arguments to "int8_t". CellPoint(int level, int face, uint32_t si, uint32_t ti) : level(level), face(face), si(si), ti(ti) {} int8_t level, face; uint32_t si, ti; }; // S2CellIds are represented in a special 64-bit format and are encoded in // fixed-size blocks. kBlockSize represents the number of values per block. // Block sizes of 4, 8, 16, and 32 were tested and kBlockSize == 16 seems to // offer the best compression. (Note that kBlockSize == 32 requires some code // modifications which have since been removed.) static constexpr int kBlockShift = 4; static constexpr size_t kBlockSize = 1 << kBlockShift; // Used to indicate that a point must be encoded as an exception (a 24-byte // S2Point) rather than as an S2CellId. static constexpr uint64_t kException = ~0ULL; // Represents the encoding parameters to be used for a given block (consisting // of kBlockSize encodable 64-bit values). See below. struct BlockCode { int delta_bits; // Delta length in bits (multiple of 4) int offset_bits; // Offset length in bits (multiple of 8) int overlap_bits; // {Delta, Offset} overlap in bits (0 or 4) }; // Returns a bit mask with "n" low-order 1 bits, for 0 <= n <= 64. inline uint64_t BitMask(int n) { return (n == 0) ? 0 : (~0ULL >> (64 - n)); } // Returns the maximum number of bits per value at the given S2CellId level. inline int MaxBitsForLevel(int level) { return 2 * level + 3; } // Returns the number of bits that "base" should be right-shifted in order to // encode only its leading "base_bits" bits, assuming that all points are // encoded at the given S2CellId level. inline int BaseShift(int level, int base_bits) { return max(0, MaxBitsForLevel(level) - base_bits); } // Forward declarations. int ChooseBestLevel(Span points, vector* cell_points); vector ConvertCellsToValues(absl::Span cell_points, int level, bool* have_exceptions); uint64_t ChooseBase(absl::Span values, int level, bool have_exceptions, int* base_bits); BlockCode GetBlockCode(Span values, uint64_t base, bool have_exceptions); // Encodes a vector of points, optimizing for space. void EncodeS2PointVectorCompact(Span points, Encoder* encoder) { // OVERVIEW // -------- // // We attempt to represent each S2Point as the center of an S2CellId. All // S2CellIds must be at the same level. Any points that cannot be encoded // exactly as S2CellId centers are stored as exceptions using 24 bytes each. // If there are so many exceptions that the CELL_IDS encoding does not save // significant space, we give up and use the uncompressed encoding. // // The first step is to choose the best S2CellId level. This requires // converting each point to (face, si, ti) coordinates and checking whether // the point can be represented exactly as an S2CellId center at some level. // We then build a histogram of S2CellId levels (just like the similar code // in S2Polygon::Encode) and choose the best level (or give up, if there are // not enough S2CellId-encodable points). // // The simplest approach would then be to take all the S2CellIds and // right-shift them to remove all the constant bits at the chosen level. // This would give the best spatial locality and hence the smallest deltas. // However instead we give up some spatial locality and use the similar but // faster transformation described below. // // Each encodable point is first converted to the (sj, tj) representation // defined below: // // sj = (((face & 3) << 30) | (si >> 1)) >> (30 - level); // tj = (((face & 4) << 29) | ti) >> (31 - level); // // These two values encode the (face, si, ti) tuple using (2 * level + 3) // bits. To see this, recall that "si" and "ti" are 31-bit values that all // share a common suffix consisting of a "1" bit followed by (30 - level) // "0" bits. The code above right-shifts these values to remove the // constant bits and then prepends the bits for "face", yielding a total of // (level + 2) bits for "sj" and (level + 1) bits for "tj". // // We then combine (sj, tj) into one 64-bit value by interleaving bit pairs: // // v = InterleaveBitPairs(sj, tj); // // (We could also interleave individual bits, but it is faster this way.) // The result is similar to right-shifting an S2CellId by (61 - 2 * level), // except that it is faster to decode and the spatial locality is not quite // as good. // // The 64-bit values are divided into blocks of size kBlockSize, and then // each value is encoded as the sum of a base value, a per-block offset, and // a per-value delta within that block: // // v[i,j] = base + offset[i] + delta[i, j] // // where "i" represents a block and "j" represents an entry in that block. // // The deltas for each block are encoded using a fixed number of 4-bit nibbles // (1-16 nibbles per delta). This allows any delta to be accessed in constant // time. // // The "offset" for each block is a 64-bit value encoded in 0-8 bytes. The // offset is left-shifted such that it overlaps the deltas by a configurable // number of bits (either 0 or 4), called the "overlap". The overlap and // offset length (0-8 bytes) are specified per block. The reason for the // overlap is that it allows fewer delta bits to be used in some cases. For // example if base == 0 and the range within a block is 0xf0 to 0x110, then // rather than using 12-bits deltas with an offset of 0, the overlap lets us // use 8-bits deltas with an offset of 0xf0 (saving 7 bytes per block). // // The global minimum value "base" is encoded using 0-7 bytes starting with // the most-significant non-zero bit possible for the chosen level. For // example, if (level == 7) then the encoded values have at most 17 bits, so // if "base" is encoded in 1 byte then it is shifted to occupy bits 9-16. // // Example: at level == 15, there are at most 33 non-zero value bits. The // following shows the bit positions covered by "base", "offset", and "delta" // assuming that "base" and "offset" are encoded in 2 bytes each, deltas are // encoded in 2 nibbles (1 byte) each, and "overlap" is 4 bits: // // Base: 1111111100000000----------------- // Offset: -------------1111111100000000---- // Delta: -------------------------00000000 // Overlap: ^^^^ // // The numbers (0 or 1) in this diagram denote the byte number of the encoded // value. Notice that "base" is shifted so that it starts at the leftmost // possible bit, "delta" always starts at the rightmost possible bit (bit 0), // and "offset" is shifted so that it overlaps "delta" by the chosen "overlap" // (either 0 or 4 bits). Also note that all of these values are summed, and // therefore each value can affect higher-order bits due to carries. // // NOTE(ericv): Encoding deltas in 4-bit rather than 8-bit length increments // reduces encoded sizes by about 7%. Allowing a 4-bit overlap between the // offset and deltas reduces encoded sizes by about 1%. Both optimizations // make the code more complex but don't affect running times significantly. // // ENCODING DETAILS // ---------------- // // Now we can move on to the actual encodings. First, there is a 2 byte // header encoded as follows: // // Byte 0, bits 0-2: encoding_format (CELL_IDS) // Byte 0, bit 3: have_exceptions // Byte 0, bits 4-7: (last_block_size - 1) // Byte 1, bits 0-2: base_bytes // Byte 1, bits 3-7: level (0-30) // // This is followed by an EncodedStringVector containing the encoded blocks. // Each block contains kBlockSize (8) values. The total size of the // EncodeS2PointVector is not stored explicitly, but instead is calculated as // // num_values == kBlockSize * (num_blocks - 1) + last_block_size . // // (An empty vector has num_blocks == 0 and last_block_size == kBlockSize.) // // Each block starts with a 1 byte header containing the following: // // Byte 0, bits 0-2: (offset_bytes - overlap_nibbles) // Byte 0, bit 3: overlap_nibbles // Byte 0, bits 4-7: (delta_nibbles - 1) // // "overlap_nibbles" is either 0 or 1 (indicating an overlap of 0 or 4 bits), // while "offset_bytes" is in the range 0-8 (indicating the number of bytes // used to encode the offset for this block). Note that some combinations // cannot be encoded: in particular, offset_bytes == 0 can only be encoded // with an overlap of 0 bits, and offset_bytes == 8 can only be encoded with // an overlap of 4 bits. This allows us to encode offset lengths of 0-8 // rather than just 0-7 without using an extra bit. (Note that the // combinations that can't be encoded are not useful anyway.) // // The header is followed by "offset_bytes" bytes for the offset, and then // (4 * delta_nibbles) bytes for the deltas. // // If there are any points that could not be represented as S2CellIds, then // "have_exceptions" in the header is true. In that case the delta values // within each block are encoded as (delta + kBlockSize), and values // 0...kBlockSize-1 are used to represent exceptions. If a block has // exceptions, they are encoded immediately following the array of deltas, // and are referenced by encoding the corresponding exception index // 0...kBlockSize-1 as the delta. // // TODO(ericv): A vector containing a single leaf cell is currently encoded as // 13 bytes (2 byte header, 7 byte base, 1 byte block count, 1 byte block // length, 1 byte block header, 1 byte delta). However if this case occurs // often, a better solution would be implement a separate format that encodes // the leading k bytes of an S2CellId. It would have a one-byte header // consisting of the encoding format (3 bits) and the number of bytes encoded // (3 bits), followed by the S2CellId bytes. The extra 2 header bits could be // used to store single points using other encodings, e.g. E7. // // If we had used 8-value blocks, we could have used the extra bit in the // first byte of the header to indicate that there is only one value, and // then skip the 2nd byte of header and the EncodedStringVector. But this // would be messy because it also requires special cases while decoding. // Essentially this would be a sub-format within the CELL_IDS format. // 1. Compute (level, face, si, ti) for each point, build a histogram of // levels, and determine the optimal level to use for encoding (if any). vector cell_points; int level = ChooseBestLevel(points, &cell_points); if (level < 0) { return EncodeS2PointVectorFast(points, encoder); } // 2. Convert the points into encodable 64-bit values. We don't use the // S2CellId itself because it requires a somewhat more complicated bit // interleaving operation. // // TODO(ericv): Benchmark using shifted S2CellIds instead. bool have_exceptions; vector values = ConvertCellsToValues(cell_points, level, &have_exceptions); // 3. Choose the global encoding parameter "base" (consisting of the bit // prefix shared by all values to be encoded). int base_bits; uint64_t base = ChooseBase(values, level, have_exceptions, &base_bits); // Now encode the output, starting with the 2-byte header (see above). int num_blocks = (values.size() + kBlockSize - 1) >> kBlockShift; int base_bytes = base_bits >> 3; encoder->Ensure(2 + base_bytes); int last_block_count = values.size() - kBlockSize * (num_blocks - 1); ABSL_DCHECK_GE(last_block_count, 0); ABSL_DCHECK_LE(last_block_count, kBlockSize); ABSL_DCHECK_LE(base_bytes, 7); ABSL_DCHECK_LE(level, 30); encoder->put8(EncodedS2PointVector::CELL_IDS | (have_exceptions << 3) | ((last_block_count - 1) << 4)); encoder->put8(base_bytes | (level << 3)); // Next we encode 0-7 bytes of "base". int base_shift = BaseShift(level, base_bits); EncodeUintWithLength(base >> base_shift, base_bytes, encoder); // Now we encode the contents of each block. StringVectorEncoder blocks; vector exceptions; for (size_t i = 0; i < values.size(); i += kBlockSize) { int block_size = min(kBlockSize, values.size() - i); BlockCode code = GetBlockCode(MakeSpan(&values[i], block_size), base, have_exceptions); // Encode the one-byte block header (see above). Encoder* block = blocks.AddViaEncoder(); int offset_bytes = code.offset_bits >> 3; int delta_nibbles = code.delta_bits >> 2; int overlap_nibbles = code.overlap_bits >> 2; block->Ensure(1 + offset_bytes + (kBlockSize / 2) * delta_nibbles); ABSL_DCHECK_LE(offset_bytes - overlap_nibbles, 7); ABSL_DCHECK_LE(overlap_nibbles, 1); ABSL_DCHECK_LE(delta_nibbles, 16); block->put8((offset_bytes - overlap_nibbles) | (overlap_nibbles << 3) | (delta_nibbles - 1) << 4); // Determine the offset for this block, and whether there are exceptions. uint64_t offset = ~0ULL; int num_exceptions = 0; for (int j = 0; j < block_size; ++j) { if (values[i + j] == kException) { num_exceptions += 1; } else { ABSL_DCHECK_GE(values[i + j], base); offset = min(offset, values[i + j] - base); } } if (num_exceptions == block_size) offset = 0; // Encode the offset. int offset_shift = code.delta_bits - code.overlap_bits; offset &= ~BitMask(offset_shift); ABSL_DCHECK_EQ(offset == 0, offset_bytes == 0); if (offset > 0) { EncodeUintWithLength(offset >> offset_shift, offset_bytes, block); } // Encode the deltas, and also gather any exceptions present. int delta_bytes = (delta_nibbles + 1) >> 1; exceptions.clear(); for (int j = 0; j < block_size; ++j) { uint64_t delta; if (values[i + j] == kException) { delta = exceptions.size(); exceptions.push_back(points[i + j]); } else { ABSL_DCHECK_GE(values[i + j], offset + base); delta = values[i + j] - (offset + base); if (have_exceptions) { ABSL_DCHECK_LE(delta, ~0ULL - kBlockSize); delta += kBlockSize; } } ABSL_DCHECK_LE(delta, BitMask(code.delta_bits)); if ((delta_nibbles & 1) && (j & 1)) { // Combine this delta with the high-order 4 bits of the previous delta. uint8_t last_byte = *(block->base() + block->length() - 1); block->RemoveLast(1); delta = (delta << 4) | (last_byte & 0xf); } EncodeUintWithLength(delta, delta_bytes, block); } // Append any exceptions to the end of the block. if (num_exceptions > 0) { int exceptions_bytes = exceptions.size() * sizeof(S2Point); block->Ensure(exceptions_bytes); block->putn(exceptions.data(), exceptions_bytes); } } blocks.Encode(encoder); } // Returns the S2CellId level for which the greatest number of the given points // can be represented as the center of an S2CellId. Initializes "cell_points" // to contain the S2CellId representation of each point (if any). Returns -1 // if there is no S2CellId that would result in significant space savings. int ChooseBestLevel(Span points, vector* cell_points) { cell_points->clear(); cell_points->reserve(points.size()); // Count the number of points at each level. int level_counts[S2CellId::kMaxLevel + 1] = { 0 }; for (const S2Point& point : points) { int face; uint32_t si, ti; int level = S2::XYZtoFaceSiTi(point, &face, &si, &ti); cell_points->push_back(CellPoint(level, face, si, ti)); if (level >= 0) ++level_counts[level]; } // Choose the level for which the most points can be encoded. int best_level = 0; for (int level = 1; level <= S2CellId::kMaxLevel; ++level) { if (level_counts[level] > level_counts[best_level]) { best_level = level; } } // The uncompressed encoding is smaller *and* faster when very few of the // points are encodable as S2CellIds. The CELL_IDS encoding uses about 1 // extra byte per point in this case, consisting of up to a 3 byte // EncodedStringVector offset for each block, a 1 byte block header, and 4 // bits per delta (encoding an exception number from 0-7), for a total of 8 // bytes per block. This represents a space overhead of about 4%, so we // require that at least 5% of the input points should be encodable as // S2CellIds in order for the CELL_IDS format to be worthwhile. constexpr double kMinEncodableFraction = 0.05; if (level_counts[best_level] <= kMinEncodableFraction * points.size()) { return -1; } return best_level; } // Given a vector of points in CellPoint format and an S2CellId level that has // been chosen for encoding, returns a vector of 64-bit values that should be // encoded in order to represent these points. Points that cannot be // represented losslessly as the center of an S2CellId at the chosen level are // indicated by the value "kException". "have_exceptions" is set to indicate // whether any exceptions were present. vector ConvertCellsToValues(absl::Span cell_points, int level, bool* have_exceptions) { vector values; values.reserve(cell_points.size()); *have_exceptions = false; int shift = S2CellId::kMaxLevel - level; for (CellPoint cp : cell_points) { if (cp.level != level) { values.push_back(kException); *have_exceptions = true; } else { // Note that bit 31 of tj is always zero, and that bits are interleaved in // such a way that bit 63 of the result is always zero. // // The S2CellId version of the following code is: // uint64_t v = S2CellId::FromFaceIJ(cp.face, cp.si >> 1, cp.ti >> 1). // parent(level).id() >> (2 * shift + 1); uint32_t sj = (((cp.face & 3) << 30) | (cp.si >> 1)) >> shift; uint32_t tj = (((cp.face & 4) << 29) | cp.ti) >> (shift + 1); uint64_t v = InterleaveUint32BitPairs(sj, tj); ABSL_DCHECK_LE(v, BitMask(MaxBitsForLevel(level))); values.push_back(v); } } return values; } uint64_t ChooseBase(absl::Span values, int level, bool have_exceptions, int* base_bits) { // Find the minimum and maximum non-exception values to be represented. uint64_t v_min = kException, v_max = 0; for (auto v : values) { if (v != kException) { v_min = min(v_min, v); v_max = max(v_max, v); } } if (v_min == kException) return 0; // Generally "base" is chosen as the bit prefix shared by v_min and v_max. // However there are a few adjustments we need to make. // // 1. Encodings are usually smaller if the bits represented by "base" and // "delta" do not overlap. Usually the shared prefix rule does this // automatically, but if v_min == v_max or there are special circumstances // that increase delta_bits (such as values.size() == 1) then we need to // make an adjustment. // // 2. The format only allows us to represent up to 7 bytes (56 bits) of // "base", so we need to ensure that "base" conforms to this requirement. int min_delta_bits = (have_exceptions || values.size() == 1) ? 8 : 4; int excluded_bits = max(absl::bit_width(v_min ^ v_max), max(min_delta_bits, BaseShift(level, 56))); uint64_t base = v_min & ~BitMask(excluded_bits); // Determine how many bytes are needed to represent this prefix. if (base == 0) { *base_bits = 0; } else { int low_bit = absl::countr_zero(base); *base_bits = (MaxBitsForLevel(level) - low_bit + 7) & ~7; } // Since base_bits has been rounded up to a multiple of 8, we may now be // able to represent additional bits of v_min. In general this reduces the // final encoded size. // // NOTE(ericv): A different strategy for choosing "base" is to encode all // blocks under the assumption that "base" equals v_min exactly, and then // set base equal to the minimum-length prefix of "v_min" that allows these // encodings to be used. This strategy reduces the encoded sizes by // about 0.2% relative to the strategy here, but is more complicated. return v_min & ~BitMask(BaseShift(level, *base_bits)); } // Returns true if the range of values [d_min, d_max] can be encoded using the // specified parameters (delta_bits, overlap_bits, and have_exceptions). bool CanEncode(uint64_t d_min, uint64_t d_max, int delta_bits, int overlap_bits, bool have_exceptions) { // "offset" can't represent the lowest (delta_bits - overlap_bits) of d_min. d_min &= ~BitMask(delta_bits - overlap_bits); // The maximum delta is reduced by kBlockSize if any exceptions exist, since // deltas 0..kBlockSize-1 are used to indicate exceptions. uint64_t max_delta = BitMask(delta_bits); if (have_exceptions) { if (max_delta < kBlockSize) return false; max_delta -= kBlockSize; } // The first test below is necessary to avoid 64-bit overflow. return (d_min > ~max_delta) || (d_min + max_delta >= d_max); } // Given a vector of 64-bit values to be encoded and an S2CellId level, returns // the optimal encoding parameters that should be used to encode each block. // Also returns the global minimum value "base" and the number of bits that // should be used to encode it ("base_bits"). BlockCode GetBlockCode(Span values, uint64_t base, bool have_exceptions) { // "b_min" and "b_max"n are the minimum and maximum values within this block. uint64_t b_min = kException, b_max = 0; for (uint64_t v : values) { if (v != kException) { b_min = min(b_min, v); b_max = max(b_max, v); } } if (b_min == kException) { // All values in this block are exceptions. return BlockCode{4, 0, 0}; } // Adjust the min/max values so that they are relative to "base". b_min -= base; b_max -= base; // Determine the minimum possible delta length and overlap that can be used // to encode this block. The block will usually be encodable using the // number of bits in (b_max - b_min) rounded up to a multiple of 4. If this // is not possible, the preferred solution is to shift "offset" so that the // delta and offset values overlap by 4 bits (since this only costs an // average of 4 extra bits per block). Otherwise we increase the delta size // by 4 bits. Certain cases require that both of these techniques are used. // // Example 1: b_min = 0x72, b_max = 0x7e. The range is 0x0c. This can be // encoded using delta_bits = 4 and overlap_bits = 0, which allows us to // represent an offset of 0x70 and a maximum delta of 0x0f, so that we can // encode values up to 0x7f. // // Example 2: b_min = 0x78, b_max = 0x84. The range is 0x0c, but in this // case it is not sufficient to use delta_bits = 4 and overlap_bits = 0 // because we can again only represent an offset of 0x70, so the maximum // delta of 0x0f only lets us encode values up to 0x7f. However if we // increase the overlap to 4 bits then we can represent an offset of 0x78, // which lets us encode values up to 0x78 + 0x0f = 0x87. // // Example 3: b_min = 0x08, b_max = 0x104. The range is 0xfc, so we should // be able to use 8-bit deltas. But even with a 4-bit overlap, we can still // only encode offset = 0 and a maximum value of 0xff. (We don't allow // bigger overlaps because statistically they are not worthwhile.) Instead // we increase the delta size to 12 bits, which handles this case easily. // // Example 4: b_min = 0xf08, b_max = 0x1004. The range is 0xfc, so we // should be able to use 8-bit deltas. With 8-bit deltas and no overlap, we // have offset = 0xf00 and a maximum encodable value of 0xfff. With 8-bit // deltas and a 4-bit overlap, we still have offset = 0xf00 and a maximum // encodable value of 0xfff. Even with 12-bit deltas, we have offset = 0 // and we can still only represent 0xfff. However with delta_bits = 12 and // overlap_bits = 4, we can represent offset = 0xf00 and a maximum encodable // value of 0xf00 + 0xfff = 0x1eff. // // It is possible to show that this last example is the worst case, i.e. we // do not need to consider increasing delta_bits or overlap_bits further. int delta_bits = (max(1, static_cast(absl::bit_width(b_max - b_min)) - 1) + 3) & ~3; int overlap_bits = 0; if (!CanEncode(b_min, b_max, delta_bits, 0, have_exceptions)) { if (CanEncode(b_min, b_max, delta_bits, 4, have_exceptions)) { overlap_bits = 4; } else { ABSL_DCHECK_LE(delta_bits, 60); delta_bits += 4; if (!CanEncode(b_min, b_max, delta_bits, 0, have_exceptions)) { ABSL_DCHECK(CanEncode(b_min, b_max, delta_bits, 4, have_exceptions)); overlap_bits = 4; } } } // When the block size is 1 and no exceptions exist, we have delta_bits == 4 // and overlap_bits == 0 which wastes 4 bits. We fix this below, which // among other things reduces the encoding size for single leaf cells by one // byte. (Note that when exceptions exist, delta_bits == 8 and overlap_bits // may be 0 or 4. These cases are covered by the unit tests.) if (values.size() == 1 && !have_exceptions) { ABSL_DCHECK(delta_bits == 4 && overlap_bits == 0); delta_bits = 8; } // Now determine the number of bytes needed to encode "offset", given the // chosen delta length. uint64_t max_delta = BitMask(delta_bits) - (have_exceptions ? kBlockSize : 0); int offset_bits = 0; if (b_max > max_delta) { // At least one byte of offset is required. Round up the minimum offset // to the next encodable value, and determine how many bits it has. int offset_shift = delta_bits - overlap_bits; uint64_t mask = BitMask(offset_shift); uint64_t min_offset = (b_max - max_delta + mask) & ~mask; ABSL_ASSUME(min_offset != 0); offset_bits = (absl::bit_width(min_offset) - offset_shift + 7) & ~7; // A 64-bit offset can only be encoded with an overlap of 4 bits. if (offset_bits == 64) overlap_bits = 4; } return BlockCode{delta_bits, offset_bits, overlap_bits}; } bool EncodedS2PointVector::InitCellIdsFormat(Decoder* decoder) { // This function inverts the encodings documented above. // First we decode the two-byte header. if (decoder->avail() < 2) return false; uint8_t header1 = decoder->get8(); uint8_t header2 = decoder->get8(); ABSL_DCHECK_EQ(header1 & 7, CELL_IDS); int last_block_count, base_bytes; cell_ids_.have_exceptions = (header1 & 8) != 0; last_block_count = (header1 >> 4) + 1; base_bytes = header2 & 7; cell_ids_.level = header2 >> 3; if (cell_ids_.level > S2CellId::kMaxLevel) return false; // Decode the base value (if any). uint64_t base; if (!DecodeUintWithLength(base_bytes, decoder, &base)) return false; cell_ids_.base = base << BaseShift(cell_ids_.level, base_bytes << 3); // Initialize the vector of encoded blocks. if (!cell_ids_.blocks.Init(decoder)) return false; size_ = kBlockSize * (cell_ids_.blocks.size() - 1) + last_block_count; // Note that the encoding format supports up to 2**59 vertices, but we // currently only support decoding up to 2**31 vertices, as // `EncodedS2PointVectorShape::num_points()` returns `int`. if (size_ > std::numeric_limits::max()) return false; return true; } S2Point EncodedS2PointVector::DecodeCellIdsFormat(int i, S2Error* error) const { // This function inverts the encodings documented above. const auto Error = [error](absl::string_view message) { if (error != nullptr) { *error = S2Error::DataLoss(message); } return S2Point(); }; // First we decode the block header. const absl::string_view block = cell_ids_.blocks[i >> kBlockShift]; if (block.empty()) { return Error("Invalid block header"); } const char* ptr = block.data(); const char* end = ptr + block.size(); uint8_t header = *ptr++; int overlap_nibbles = (header >> 3) & 1; int offset_bytes = (header & 7) + overlap_nibbles; int delta_nibbles = (header >> 4) + 1; // Decode the offset for this block. If offset_bytes is zero, we don't have // an offset so we can skip decoding it. It's possible to get an offset_shift // of 64 in this case, so skipping prevents us from shifting by that amount // and triggering undefined behavior. uint64_t offset = 0; if (offset_bytes > 0) { int offset_shift = (delta_nibbles - overlap_nibbles) << 2; // TODO(b/267575159): detect root cause for shift exponent overflow earlier? if (offset_shift >= 64) { return Error("Invalid offset_shift"); } if (ptr + offset_bytes > end) { return Error("Invalid offset outside of block size"); } offset = GetUintWithLength(ptr, offset_bytes) << offset_shift; ptr += offset_bytes; } // Decode the delta for the requested value. int delta_nibble_offset = (i & (kBlockSize - 1)) * delta_nibbles; int delta_bytes = (delta_nibbles + 1) >> 1; const char* delta_ptr = ptr + (delta_nibble_offset >> 1); if (delta_ptr + delta_bytes > end) { return Error("Invalid delta outside of block size"); } uint64_t delta = GetUintWithLength(delta_ptr, delta_bytes); delta >>= (delta_nibble_offset & 1) << 2; delta &= BitMask(delta_nibbles << 2); // Test whether this point is encoded as an exception. if (cell_ids_.have_exceptions) { if (delta < kBlockSize) { int block_size = min(kBlockSize, size_ - (i & ~(kBlockSize - 1))); ptr += (block_size * delta_nibbles + 1) >> 1; ptr += delta * sizeof(S2Point); if (ptr + sizeof(S2Point) > end) { return Error("Invalid exception delta outside of block size"); } return *reinterpret_cast(ptr); } delta -= kBlockSize; } // Otherwise convert the 64-bit value back to an S2Point. uint64_t value = cell_ids_.base + offset + delta; int shift = S2CellId::kMaxLevel - cell_ids_.level; // The S2CellId version of the following code is: // return S2CellId(((value << 1) | 1) << (2 * shift)).ToPoint(); uint32_t sj, tj; DeinterleaveUint32BitPairs(value, &sj, &tj); int si = (((sj << 1) | 1) << shift) & 0x7fffffff; int ti = (((tj << 1) | 1) << shift) & 0x7fffffff; int face = ((sj << shift) >> 30) | (((tj << (shift + 1)) >> 29) & 4); return S2::FaceUVtoXYZ(face, S2::STtoUV(S2::SiTitoST(si)), S2::STtoUV(S2::SiTitoST(ti))).Normalize(); } } // namespace s2coding src/s2/encoded_s2point_vector.h000066400000000000000000000157641524103652300170210ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_ENCODED_S2POINT_VECTOR_H_ #define S2_ENCODED_S2POINT_VECTOR_H_ #include #include #include #include #include "absl/base/optimization.h" #include "absl/log/absl_log.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/encoded_string_vector.h" #include "s2/encoded_uint_vector.h" #include "s2/s2coder.h" #include "s2/s2error.h" #include "s2/s2point.h" namespace s2coding { // Encodes a vector of S2Points in a format that can later be decoded as an // EncodedS2PointVector. // // REQUIRES: "encoder" uses the default constructor, so that its buffer // can be enlarged as necessary by calling Ensure(int). void EncodeS2PointVector(absl::Span points, CodingHint hint, Encoder* encoder); // This class represents an encoded vector of S2Points. Values are decoded // only when they are accessed. This allows for very fast initialization and // no additional memory use beyond the encoded data. The encoded data is not // owned by this class; typically it points into a large contiguous buffer // that contains other encoded data as well. // // This is one of several helper classes that allow complex data structures to // be initialized from an encoded format in constant time and then decoded on // demand. This can be a big performance advantage when only a small part of // the data structure is actually used. class EncodedS2PointVector { public: // Constructs an uninitialized object; requires Init() to be called. EncodedS2PointVector() {} // Initializes the EncodedS2PointVector. // // Encoded types do not necessarily read all of their data when calling // Init(), instead only data necessary to decode further is read, which means // that encoded types may in general log DFATAL errors when reading from an // untrusted byte stream using unchecked accessors (e.g. operator[]). // // Checked accessors such as Decode(S2Error&) will instead set an error // condition, at the cost of potentially more overhead when decoding. // // REQUIRES: The Decoder data buffer must outlive this object. [[nodiscard]] bool Init(Decoder* decoder); // Initializes the EncodedS2PointVector as above. Setting S2Error if // initialization fails. A true return status does -not- mean that the byte // stream is without errors. The individual points must still be checked with // a checked accessor such as Decode(S2Error&). [[nodiscard]] bool Init(Decoder* decoder, S2Error& error); // Returns the size of the original vector. size_t size() const; // Returns the element at the given index. S2Point operator[](int i) const; // Decodes and returns the entire original vector. std::vector Decode() const; // Decodes the entire original vector and stores it in the given span. bool Decode(absl::Span points) const; // Decodes and returns the entire original vector, checking for errors as it // goes. If an error occurs, a truncated vector is returned. std::vector Decode(S2Error& error) const; // Decodes the entire original vector and stores it in the given span. Checks // for errors as it goes. If an error occurs returns false and the span may // be incompletely written. bool Decode(absl::Span points, S2Error& error) const; // Copy the encoded data to the encoder. This allows for "reserialization" of // encoded shapes created through lazy decoding. void Encode(Encoder* encoder) const; // TODO(ericv): Consider adding a method that returns an adjacent pair of // points. This would save some decoding overhead. private: friend void EncodeS2PointVector(absl::Span, CodingHint, Encoder*); friend void EncodeS2PointVectorFast(absl::Span, Encoder*); friend void EncodeS2PointVectorCompact(absl::Span, Encoder*); // Decodes and returns the point at the given index. If any errors occur when // decoding, the error is set and a default constructed point returned. S2Point At(int i, S2Error& error) const; bool InitUncompressedFormat(Decoder* decoder); bool InitCellIdsFormat(Decoder* decoder); S2Point DecodeCellIdsFormat(int i, S2Error* error) const; // We use a tagged union to represent multiple formats, as opposed to an // abstract base class or templating. This represents the best compromise // between performance, space, and convenience. Note that the overhead of // checking the tag is trivial and will typically be branch-predicted // perfectly. // // TODO(ericv): Once additional formats have been implemented, consider // using std::variant<> instead. It's unclear whether this would have // better or worse performance than the current approach. enum Format : uint8_t { UNCOMPRESSED = 0, CELL_IDS = 1, }; Format format_; uint32_t size_; union { struct { const S2Point* points; } uncompressed_; struct { EncodedStringVector blocks; uint64_t base; uint8_t level; bool have_exceptions; // TODO(ericv): Use std::atomic_flag to cache the last point decoded in // a thread-safe way. This reduces benchmark times for actual polygon // operations (e.g. S2ClosestEdgeQuery) by about 15%. } cell_ids_; }; }; ////////////////// Implementation details follow //////////////////// inline size_t EncodedS2PointVector::size() const { return size_; } inline S2Point EncodedS2PointVector::At(int i, S2Error& error) const { switch (format_) { case Format::UNCOMPRESSED: return uncompressed_.points[i]; case Format::CELL_IDS: return DecodeCellIdsFormat(i, &error); default: error = S2Error::DataLoss("Unrecognized format"); return {}; } ABSL_UNREACHABLE(); } inline S2Point EncodedS2PointVector::operator[](int i) const { // Check error conditions in debug mode, elide them otherwise. #ifndef NDEBUG S2Error error; S2Point point = At(i, error); if (!error.ok()) { ABSL_LOG(DFATAL) << error.message(); } return point; #else switch (format_) { case Format::UNCOMPRESSED: return uncompressed_.points[i]; case Format::CELL_IDS: return DecodeCellIdsFormat(i, nullptr); default: return {}; } ABSL_UNREACHABLE(); #endif } } // namespace s2coding #endif // S2_ENCODED_S2POINT_VECTOR_H_ src/s2/encoded_s2point_vector_test.cc000066400000000000000000000555651524103652300202210ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_s2point_vector.h" #include #include #include #include #include #include #include "absl/log/absl_check.h" #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "absl/strings/str_cat.h" #include "absl/strings/str_format.h" #include "s2/base/log_severity.h" #include "s2/util/bits/bit-interleave.h" #include "s2/util/coding/coder.h" #include "s2/s2cell_id.h" #include "s2/s2coder.h" #include "s2/s2coords.h" #include "s2/s2fractal.h" #include "s2/s2loop.h" #include "s2/s2point.h" #include "s2/s2polygon.h" #include "s2/s2random.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" #include "s2/util/math/matrix3x3.h" using s2textformat::MakeCellIdOrDie; using s2textformat::MakePointOrDie; using std::make_unique; using std::vector; namespace s2coding { static int kBlockSize = 16; // Number of deltas per block in implementation. size_t TestEncodedS2PointVector(const vector& expected, CodingHint hint, int64_t expected_bytes) { Encoder encoder; EncodeS2PointVector(expected, hint, &encoder); if (expected_bytes >= 0) { EXPECT_EQ(expected_bytes, encoder.length()); } // Allocate storage aligned to double. Since there is a varint at the // beginning of the encoding, the following S2Points will be unaligned, // so we test unaligned S2Point access for UNCOMPRESSED encodings. auto aligned = make_unique(encoder.length() / sizeof(double) + 1); std::memcpy(aligned.get(), encoder.base(), encoder.length()); { // Test un-checked decoding path. Decoder decoder(aligned.get(), encoder.length()); EncodedS2PointVector actual; EXPECT_TRUE(actual.Init(&decoder)); EXPECT_EQ(actual.Decode(), expected); } { // Test checked decoding path. Decoder decoder(aligned.get(), encoder.length()); EncodedS2PointVector actual; S2Error error; EXPECT_TRUE(actual.Init(&decoder, error)); EXPECT_TRUE(error.ok()) << error.message(); EXPECT_EQ(actual.Decode(error), expected); EXPECT_TRUE(error.ok()) << error.message(); } return encoder.length(); } // In order to make it easier to construct tests that encode particular // values, this function duplicates the part of EncodedS2PointVector that // converts an encoded 64-bit value back to an S2Point. S2Point EncodedValueToPoint(uint64_t value, int level) { uint32_t sj, tj; util_bits::DeinterleaveUint32(value, &sj, &tj); int shift = S2CellId::kMaxLevel - level; int si = (((sj << 1) | 1) << shift) & 0x7fffffff; int ti = (((tj << 1) | 1) << shift) & 0x7fffffff; int face = ((sj << shift) >> 30) | (((tj << (shift + 1)) >> 29) & 4); return S2::FaceUVtoXYZ(face, S2::STtoUV(S2::SiTitoST(si)), S2::STtoUV(S2::SiTitoST(ti))).Normalize(); } TEST(EncodedS2PointVectorTest, Empty) { TestEncodedS2PointVector({}, CodingHint::FAST, 1); // Test that an empty vector uses the UNCOMPRESSED encoding. TestEncodedS2PointVector({}, CodingHint::COMPACT, 1); } TEST(EncodedS2PointVectorTest, OnePoint) { TestEncodedS2PointVector({S2Point(1, 0, 0)}, CodingHint::FAST, 25); // Encoding: header (2 bytes), block count (1 byte), block offsets (1 byte), // block header (1 byte), delta (1 byte). TestEncodedS2PointVector({S2Point(1, 0, 0)}, CodingHint::COMPACT, 6); } TEST(EncodedS2PointVectorTest, OnePointWithExceptionsNoOverlap) { // Test encoding a block with one point when other blocks have exceptions // (which changes the encoding for all blocks). The case below yields // delta_bits == 8 and overlap_bits == 0. // // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes) // Block 0: block header (1 byte), 16 deltas (16 bytes), exception (24 bytes) // Block 1: block header (1 byte), delta (1 byte) S2Point a(1, 0, 0); vector points = { S2Point(1, 2, 3).Normalize(), a, a, a, a, a, a, a, a, a, a, a, a, a, a, a, a // Second block }; TestEncodedS2PointVector(points, CodingHint::COMPACT, 48); } TEST(EncodedS2PointVectorTest, OnePointWithExceptionsWithOverlap) { // Test encoding a block with one point when other blocks have exceptions // (which changes the encoding for all blocks). The case below yields // delta_bits == 8 and overlap_bits == 4. // // Encoding: header (2 bytes), base (2 bytes), block count (1 byte), // block offsets (2 bytes) // Block 0: header (1 byte), offset (2 bytes), 16 deltas (16 bytes), // exception (24 bytes) // Block 1: header (1 byte), offset (2 bytes), delta (1 byte) S2Point a = S2CellId(0x946df618d0000000).ToPoint(); S2Point b = S2CellId(0x947209e070000000).ToPoint(); vector points = { S2Point(1, 2, 3).Normalize(), a, a, a, a, a, a, a, a, a, a, a, a, a, a, a, b // Second block }; TestEncodedS2PointVector(points, CodingHint::COMPACT, 54); } TEST(EncodedS2PointVectorTest, CellIdWithException) { // Test one point encoded as an S2CellId with one point encoded as an // exception. // // Encoding: header (2 bytes), block count (1 byte), block offsets (1 byte), // block header (1 byte), two deltas (2 bytes), exception (24 bytes). TestEncodedS2PointVector( {MakeCellIdOrDie("1/23").ToPoint(), S2Point(0.1, 0.2, 0.3).Normalize()}, CodingHint::COMPACT, 31); } TEST(EncodedS2PointVectorTest, PointsAtMultipleLevels) { // Test that when points at multiple levels are present, the level with the // most points is chosen (preferring the smallest level in case of ties). // (All other points are encoded as exceptions.) // In this example, the two points at level 5 (on face 1) should be encoded. // It is possible to tell which points are encoded by the length of the // encoding (since different numbers of "base" bytes are encoded). // // Encoding: header (2 bytes), base (1 byte), block count (1 byte), block // offsets (1 byte), block header (1 byte), 5 deltas (5 bytes), S2Point // exceptions (72 bytes). TestEncodedS2PointVector( {MakeCellIdOrDie("2/11001310230102").ToPoint(), MakeCellIdOrDie("1/23322").ToPoint(), MakeCellIdOrDie("3/3").ToPoint(), MakeCellIdOrDie("1/23323").ToPoint(), MakeCellIdOrDie("2/12101023022012").ToPoint()}, CodingHint::COMPACT, 83); } TEST(EncodedS2PointVectorTest, NoOverlapOrExtraDeltaBitsNeeded) { // This function tests the case in GetBlockCodes() where values can be // encoded using the minimum number delta bits and no overlap. From the // comments there: // // Example 1: b_min = 0x72, b_max = 0x7e. The range is 0x0c. This can be // encoded using delta_bits = 4 and overlap_bits = 0, which allows us to // represent an offset of 0x70 and a maximum delta of 0x0f, so that we can // encode values up to 0x7f. // // To set up this test, we need at least two blocks: one to set the global // minimum value, and the other to encode a specific range of deltas. To // make things easier, the first block has a minimum value of zero. // // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes) // Block 0: header (1 byte), 8 deltas (8 bytes) // Block 1: header (1 byte), offset (1 byte), 4 deltas (2 bytes) const int level = 3; vector points(kBlockSize, EncodedValueToPoint(0, level)); points.push_back(EncodedValueToPoint(0x72, level)); points.push_back(EncodedValueToPoint(0x74, level)); points.push_back(EncodedValueToPoint(0x75, level)); points.push_back(EncodedValueToPoint(0x7e, level)); TestEncodedS2PointVector(points, CodingHint::COMPACT, 10 + kBlockSize / 2); } TEST(EncodedS2PointVectorTest, OverlapNeeded) { // Like the above, but tests the following case: // // Example 2: b_min = 0x78, b_max = 0x84. The range is 0x0c, but in this // case it is not sufficient to use delta_bits = 4 and overlap_bits = 0 // because we can again only represent an offset of 0x70, so the maximum // delta of 0x0f only lets us encode values up to 0x7f. However if we // increase the overlap to 4 bits then we can represent an offset of 0x78, // which lets us encode values up to 0x78 + 0x0f = 0x87. // // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes) // Block 0: header (1 byte), 8 deltas (8 bytes) // Block 1: header (1 byte), offset (1 byte), 4 deltas (2 bytes) const int level = 3; vector points(kBlockSize, EncodedValueToPoint(0, level)); points.push_back(EncodedValueToPoint(0x78, level)); points.push_back(EncodedValueToPoint(0x7a, level)); points.push_back(EncodedValueToPoint(0x7c, level)); points.push_back(EncodedValueToPoint(0x84, level)); TestEncodedS2PointVector(points, CodingHint::COMPACT, 10 + kBlockSize / 2); } TEST(EncodedS2PointVectorTest, ExtraDeltaBitsNeeded) { // Like the above, but tests the following case: // // Example 3: b_min = 0x08, b_max = 0x104. The range is 0xfc, so we should // be able to use 8-bit deltas. But even with a 4-bit overlap, we can still // only encode offset = 0 and a maximum value of 0xff. (We don't allow // bigger overlaps because statistically they are not worthwhile.) Instead // we increase the delta size to 12 bits, which handles this case easily. // // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes) // Block 0: header (1 byte), 8 deltas (8 bytes) // Block 1: header (1 byte), 4 deltas (6 bytes) const int level = 3; vector points(kBlockSize, EncodedValueToPoint(0, level)); points.push_back(EncodedValueToPoint(0x08, level)); points.push_back(EncodedValueToPoint(0x4e, level)); points.push_back(EncodedValueToPoint(0x82, level)); points.push_back(EncodedValueToPoint(0x104, level)); TestEncodedS2PointVector(points, CodingHint::COMPACT, 13 + kBlockSize / 2); } TEST(EncodedS2PointVectorTest, ExtraDeltaBitsAndOverlapNeeded) { // Like the above, but tests the following case: // // Example 4: d_min = 0xf08, d_max = 0x1004. The range is 0xfc, so we // should be able to use 8-bit deltas. With 8-bit deltas and no overlap, we // have offset = 0xf00 and a maximum encodable value of 0xfff. With 8-bit // deltas and a 4-bit overlap, we still have offset = 0xf00 and a maximum // encodable value of 0xfff. Even with 12-bit deltas, we have offset = 0 // and we can still only represent 0xfff. However with delta_bits = 12 and // overlap_bits = 4, we can represent offset = 0xf00 and a maximum encodable // value of 0xf00 + 0xfff = 0x1eff. // // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes) // Block 0: header (1 byte), 8 deltas (8 bytes) // Block 1: header (1 byte), offset (1 byte), 4 deltas (6 bytes) const int level = 5; vector points(kBlockSize, EncodedValueToPoint(0, level)); points.push_back(EncodedValueToPoint(0xf08, level)); points.push_back(EncodedValueToPoint(0xf4e, level)); points.push_back(EncodedValueToPoint(0xf82, level)); points.push_back(EncodedValueToPoint(0x1004, level)); TestEncodedS2PointVector(points, CodingHint::COMPACT, 14 + kBlockSize / 2); } TEST(EncodedS2PointVectorTest, SixtyFourBitOffset) { // Tests a case where a 64-bit block offset is needed. // // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes) // Block 0: header (1 byte), 8 deltas (8 bytes) // Block 1: header (1 byte), offset (8 bytes), 2 deltas (1 byte) const int level = S2CellId::kMaxLevel; vector points(kBlockSize, S2CellId::Begin(level).ToPoint()); points.push_back(S2CellId::End(level).prev().ToPoint()); points.push_back(S2CellId::End(level).prev().prev().ToPoint()); TestEncodedS2PointVector(points, CodingHint::COMPACT, 16 + kBlockSize / 2); } TEST(EncodedS2PointVectorTest, AllExceptionsBlock) { // The encoding consists of two blocks; the first contains 16 encodable // values, while the second contains two exceptions. vector points(kBlockSize, EncodedValueToPoint(0, S2CellId::kMaxLevel)); points.push_back(S2Point(0.1, 0.2, 0.3).Normalize()); points.push_back(S2Point(0.3, 0.2, 0.1).Normalize()); // Encoding: header (2 bytes), block count (1 byte), block offsets (2 bytes). // 1st block header (1 byte), 16 deltas (16 bytes). // 2nd block header (1 byte), 2 deltas (1 byte), 2 exceptions (48 bytes). TestEncodedS2PointVector(points, CodingHint::COMPACT, 72); // Encoding: header (2 bytes), 18 S2Points (432 bytes). TestEncodedS2PointVector(points, CodingHint::FAST, 434); } TEST(EncodedS2PointVectorTest, FirstAtAllLevels) { // Test encoding the first S2CellId at each level (which also happens to have // the maximum face, si, and ti values). All such S2CellIds can be encoded in // 6 bytes because most of the bits are zero. for (int level = 0; level <= S2CellId::kMaxLevel; ++level) { SCOPED_TRACE(absl::StrCat("Level = ", level)); TestEncodedS2PointVector({S2CellId::Begin(level).ToPoint()}, CodingHint::COMPACT, 6); } } TEST(EncodedS2PointVectorTest, LastAtAllLevels) { // Test encoding the last S2CellId at each level. It turns out that such // S2CellIds have the largest possible face and ti values, and the minimum // possible si value at that level. Such S2CellIds can be encoded in 6 to 13 // bytes depending on the level. for (int level = 0; level <= S2CellId::kMaxLevel; ++level) { SCOPED_TRACE(absl::StrCat("Level = ", level)); // Note that 8 bit deltas are used to encode blocks of size 1, which // reduces the size of "base" from ((level + 2) / 4) to (level / 4) bytes. int expected_size = 6 + level / 4; TestEncodedS2PointVector({S2CellId::End(level).prev().ToPoint()}, CodingHint::COMPACT, expected_size); } } TEST(EncodedS2PointVectorTest, MaxFaceSiTiAtAllLevels) { // Similar to the test above, but tests encoding the S2CellId at each level // whose face, si, and ti values are all maximal. This turns out to be the // S2CellId whose human-readable form is 5/222...22 (0xb555555555555555), // however for clarity we construct it using S2CellId::FromFaceIJ. for (int level = 0; level <= S2CellId::kMaxLevel; ++level) { SCOPED_TRACE(absl::StrCat("Level = ", level)); S2CellId id = S2CellId::FromFaceIJ(5, S2::kLimitIJ - 1, S2::kLimitIJ - 1) .parent(level); // This encoding is one byte bigger than the previous test at levels 7, 11, // 15, 19, 23, and 27. This is because in the previous test, the // odd-numbered value bits are all zero (except for the face number), which // reduces the number of base bits needed by exactly 1. The encoding size // at level==3 is unaffected because for singleton blocks, the lowest 8 // value bits are encoded in the delta. int expected_size = (level < 4) ? 6 : 6 + (level + 1) / 4; TestEncodedS2PointVector({id.ToPoint()}, CodingHint::COMPACT, expected_size); } } TEST(EncodedS2PointVectorTest, LastTwoPointsAtAllLevels) { // Test encoding the last two S2CellIds at each level. for (int level = 0; level <= S2CellId::kMaxLevel; ++level) { SCOPED_TRACE(absl::StrCat("Level = ", level)); S2CellId id = S2CellId::End(level).prev(); // Notice that this costs only 4 bits more than encoding the last S2CellId // by itself (see LastAtAllLevels). This is because encoding a block of // size 1 uses 8-bit deltas (which reduces the size of "base" by 4 bits), // while this test uses two 4-bit deltas. int expected_size = 6 + (level + 2) / 4; TestEncodedS2PointVector({id.ToPoint(), id.prev().ToPoint()}, CodingHint::COMPACT, expected_size); } } TEST(EncodedS2PointVectorTest, ManyDuplicatePointsAtAllLevels) { // Test encoding 32 copies of the last S2CellId at each level. This uses // between 27 and 38 bytes depending on the level. (Note that the encoding // can use less than 1 byte per point in this situation.) for (int level = 0; level <= S2CellId::kMaxLevel; ++level) { SCOPED_TRACE(absl::StrCat("Level = ", level)); S2CellId id = S2CellId::End(level).prev(); // Encoding: header (2 bytes), base ((level + 2) / 4 bytes), block count // (1 byte), block offsets (2 bytes), block headers (2 bytes), 32 deltas // (16 bytes). At level 30 the encoding size goes up by 1 byte because // we can't encode an 8 byte "base" value, so instead this case uses a // base of 7 bytes plus a one-byte offset in each of the 2 blocks. int expected_size = 23 + (level + 2) / 4; if (level == 30) expected_size += 1; vector points(32, id.ToPoint()); TestEncodedS2PointVector(points, CodingHint::COMPACT, expected_size); } } TEST(EncodedS2PointVectorTest, SnappedFractalLoops) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "SNAPPED_FRACTAL_LOOPS", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); int kMaxPoints = 3 << 14; for (int num_points = 3; num_points <= kMaxPoints; num_points *= 4) { size_t s2polygon_size = 0, lax_polygon_size = 0; for (int i = 0; i < 10; ++i) { S2Fractal fractal(bitgen); fractal.SetLevelForApproxMaxEdges(num_points); Matrix3x3_d frame = s2random::Frame(bitgen); auto loop = fractal.MakeLoop(frame, S2Testing::KmToAngle(10)); vector points; for (int j = 0; j < loop->num_vertices(); ++j) { points.push_back(S2CellId(loop->vertex(j)).ToPoint()); } S2Polygon s2polygon(make_unique(points)); Encoder encoder; s2polygon.Encode(&encoder); s2polygon_size += encoder.length(); // S2LaxPolygonShape has 2 extra bytes of overhead to encode one loop. lax_polygon_size += TestEncodedS2PointVector(points, CodingHint::COMPACT, -1) + 2; } absl::PrintF("n=%5d s2=%9zu lax=%9zu\n", num_points, s2polygon_size, lax_polygon_size); } } void TestRoundtripEncoding(s2coding::CodingHint hint) { // Ensures that the EncodedS2PointVector can be encoded and decoded without // loss. const int level = 3; vector points(kBlockSize, EncodedValueToPoint(0, level)); points.push_back(EncodedValueToPoint(0x78, level)); points.push_back(EncodedValueToPoint(0x7a, level)); points.push_back(EncodedValueToPoint(0x7c, level)); points.push_back(EncodedValueToPoint(0x84, level)); EncodedS2PointVector a_vector; Encoder a_encoder; EncodedS2PointVector b_vector; Encoder b_encoder; // Encode and decode from a vector. { EncodeS2PointVector(points, hint, &a_encoder); Decoder decoder(a_encoder.base(), a_encoder.length()); ASSERT_TRUE(a_vector.Init(&decoder)); } ASSERT_EQ(points, a_vector.Decode()); // Encode and decode from an EncodedS2PointVector. { a_vector.Encode(&b_encoder); Decoder decoder(b_encoder.base(), b_encoder.length()); ASSERT_TRUE(b_vector.Init(&decoder)); } EXPECT_EQ(points, b_vector.Decode()); } TEST(EncodedS2PointVectorTest, RoundtripEncodingFast) { TestRoundtripEncoding(s2coding::CodingHint::FAST); } TEST(EncodedS2PointVectorTest, RoundtripEncodingCompact) { TestRoundtripEncoding(s2coding::CodingHint::COMPACT); } static void EncodePoints(int num_points, CodingHint hint, Encoder* encoder) { vector points = S2Testing::MakeRegularPoints( MakePointOrDie("23:16"), S2Testing::KmToAngle(10), num_points); for (S2Point& point : points) { point = S2CellId(point).ToPoint(); } EncodeS2PointVector(points, hint, encoder); } // Measures accessing points sequentially. This corresponds to the use case // where the vector is decoded upon initialization (e.g., S2LaxPolygonShape). static void BM_DecodePointSequentially(benchmark::State& state) { CodingHint hint = state.range(0) ? CodingHint::COMPACT : CodingHint::FAST; int num_points = state.range(1); Encoder encoder; EncodePoints(num_points, hint, &encoder); EncodedS2PointVector encoded_points; Decoder decoder(encoder.base(), encoder.length()); ABSL_CHECK(encoded_points.Init(&decoder)); std::vector points(num_points); while (state.KeepRunningBatch(num_points)) { for (int i = 0; i < num_points; ++i) { points[i] = encoded_points[i]; } } benchmark::DoNotOptimize(points); state.SetItemsProcessed(state.iterations()); } BENCHMARK(BM_DecodePointSequentially) ->ArgPair(0, 10)->ArgPair(0, 10000) ->ArgPair(1, 10)->ArgPair(1, 10000); // Measures accessing edges (adjacent point pairs) sequentially. This // corresponds to the common situation where the edges in an S2ShapeIndex cell // span a contiguous range of edge ids. The big difference compared to the // benchmark above is that each point is accessed twice in a row, since the // last vertex of one edge is typically the same as the first vertex of the // next edge. static void BM_GetEdgeSequentially(benchmark::State& state) { CodingHint hint = state.range(0) ? CodingHint::COMPACT : CodingHint::FAST; int num_points = state.range(1); Encoder encoder; EncodePoints(num_points, hint, &encoder); EncodedS2PointVector encoded_points; Decoder decoder(encoder.base(), encoder.length()); ABSL_CHECK(encoded_points.Init(&decoder)); std::vector points(num_points); while (state.KeepRunningBatch(num_points - 1)) { for (int i = 0; i < num_points - 1; ++i) { points[i] = encoded_points[i]; points[i + 1] = encoded_points[i + 1]; } } benchmark::DoNotOptimize(points); state.SetItemsProcessed(state.iterations() * 2); } BENCHMARK(BM_GetEdgeSequentially) ->ArgPair(0, 10)->ArgPair(0, 10000) ->ArgPair(1, 10)->ArgPair(1, 10000); // Fuzz testing of the decoder. void DecodePointVector(std::string data) { EncodedS2PointVector v; Decoder decoder(data.data(), data.size()); S2Error error; if (v.Init(&decoder, error)) { v.Decode(error); } } TEST(EncodedS2PointVectorTest, DecodeNeverCrashesRegression1) { DecodePointVector("i\370\305\201"); } TEST(EncodedS2PointVectorTest, DecodeNeverCrashesRegression2) { DecodePointVector( "\201\252\305+\010\023\304\n\274\3271^7\261\261iiY\261\261\261\261\261" "\253\313\220\254DDDDV\320"); } TEST(EncodedS2PointVectorTest, DecodeNeverCrashesRegression3) { DecodePointVector( "\351\010\010\010\010\010\0107\274\361\030fo[\210O\363\214]\010\021n" "\265W=(\014\014\014\014\203\034"); } TEST(EncodedS2PointVectorTest, DecodeNeverCrashesRegression4) { DecodePointVector( "\331\010\010\014\363+\214O\230\200\230{$$\314$\210b\222\034\210\210\232" "\210\210\212\214\034"); } } // namespace s2coding src/s2/encoded_s2shape_index.cc000066400000000000000000000175641524103652300167330ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_s2shape_index.h" #include #include #include #include #include #include "s2/base/casts.h" #include "absl/base/optimization.h" #include "absl/numeric/bits.h" #include "s2/util/coding/coder.h" #include "s2/util/coding/varint.h" #include "s2/encoded_s2cell_id_vector.h" #include "s2/encoded_string_vector.h" #include "s2/mutable_s2shape_index.h" #include "s2/s2cell_id.h" #include "s2/s2point.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" using std::make_unique; using std::unique_ptr; using std::vector; S2Shape* EncodedS2ShapeIndex::GetShape(int id) const { // This method is called when a shape has not been decoded yet. unique_ptr shape = (*shape_factory_)[id]; S2Shape* expected = kUndecodedShape(); if (shapes_[id].compare_exchange_strong(expected, shape.get(), std::memory_order_acq_rel)) { return shape.release(); // Ownership has been transferred to shapes_. } return expected; // Another thread updated shapes_[id] first. } const S2ShapeIndexCell* EncodedS2ShapeIndex::GetCell(int i) const { // memory_order_release ensures that no reads or writes in the current // thread can be reordered after this store, and all writes in the current // thread are visible to other threads that acquire the same atomic // variable. // // memory_order_acquire ensures that no reads or writes in the current // thread can be reordered before this load, and all writes in other threads // that release the same atomic variable are visible in this thread. // // We use this to implement lock-free synchronization on the read path as // follows: // // 1. cells_decoded(i) is updated using acquire/release semantics // 2. cells_[i] is written before cells_decoded(i) // 3. cells_[i] is read after cells_decoded(i) // // Note that we do still use a lock for the write path to ensure that // cells_[i] and cell_decoded(i) are updated together atomically. if (cell_decoded(i)) return cells_[i]; // Decode the cell before acquiring the spinlock in order to minimize the // time that the lock is held. auto cell = make_unique(); Decoder decoder = encoded_cells_.GetDecoder(i); if (!cell->Decode(num_shape_ids(), &decoder)) { return nullptr; } // Recheck cell_decoded(i) once we hold the lock in case another thread // has decoded this cell in the meantime. SpinLockHolder l(cells_lock_); if (cell_decoded(i)) return cells_[i]; // Update the cell, setting cells_[i] before cell_decoded(i). cells_[i] = cell.get(); set_cell_decoded(i); if (cell_cache_.size() < static_cast(max_cell_cache_size())) { cell_cache_.push_back(i); } return cell.release(); // Ownership has been transferred to cells_. } EncodedS2ShapeIndex::EncodedS2ShapeIndex() = default; EncodedS2ShapeIndex::~EncodedS2ShapeIndex() { // Although Minimize() does slightly more than required for destruction // (i.e., it resets vector elements to their default values), this does not // affect benchmark times. Minimize(); } bool EncodedS2ShapeIndex::Init(Decoder* decoder, const ShapeFactory& shape_factory) { Minimize(); uint64_t max_edges_version; if (!decoder->get_varint64(&max_edges_version)) return false; version_ = max_edges_version & 3; if (version_ != MutableS2ShapeIndex::kCurrentEncodingVersionNumber) { return false; } options_.set_max_edges_per_cell(max_edges_version >> 2); // AtomicShape is a subtype of std::atomic that changes the // default constructor value to kUndecodedShape(). This saves the effort of // initializing all the elements twice. shapes_ = vector(shape_factory.size()); shape_factory_ = shape_factory.Clone(); if (!cell_ids_.Init(decoder)) return false; // The cells_ elements are *uninitialized memory*. Instead we have bit // vector (cells_decoded_) to indicate which elements of cells_ are valid. // This reduces constructor times by more than a factor of 50, since rather // than needing to initialize one 64-bit pointer per cell to zero, we only // need to initialize one bit per cell to zero. // // For very large S2ShapeIndexes the internal memset() call to initialize // cells_decoded_ still takes about 1.3 microseconds per million cells // (assuming an optimized implementation that writes 32 bytes per cycle), // but this seems reasonable relative to other likely costs (I/O, etc). // // NOTE(ericv): DO NOT use make_unique<> here! make_unique<> allocates memory // using "new T[n]()", which initializes all elements of the array. This // slows down some benchmarks by over 100x. // // cells_ = make_unique[](cell_ids_.size()); // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ // NO NO NO cells_.reset(new S2ShapeIndexCell*[cell_ids_.size()]); cells_decoded_ = vector>((cell_ids_.size() + 63) >> 6); return encoded_cells_.Init(decoder); } void EncodedS2ShapeIndex::Encode(Encoder* encoder) const { // Re-encode the max edges and version number. encoder->Ensure(Varint::kMax64); uint64_t max_edges = options_.max_edges_per_cell(); encoder->put_varint64(max_edges << 2 | version_); // And copy the encoded cell ids and cells. cell_ids_.Encode(encoder); encoded_cells_.Encode(encoder); } void EncodedS2ShapeIndex::Minimize() { if (cells_ == nullptr) return; // Not initialized yet. for (auto& atomic_shape : shapes_) { S2Shape* shape = atomic_shape.load(std::memory_order_relaxed); if (shape != kUndecodedShape() && shape != nullptr) { atomic_shape.store(kUndecodedShape(), std::memory_order_relaxed); delete shape; } } if (cell_cache_.size() < static_cast(max_cell_cache_size())) { // When only a tiny fraction of the cells are decoded, we keep track of // those cells in cell_cache_ to avoid the cost of scanning the // cells_decoded_ vector. (The cost is only about 1 cycle per 64 cells, // but for a huge polygon with 1 million cells that's still 16000 cycles.) for (int pos : cell_cache_) { cells_decoded_[pos >> 6].store(0, std::memory_order_relaxed); delete cells_[pos]; } } else { // Scan the cells_decoded_ vector looking for cells that must be deleted. for (int i = cells_decoded_.size(); --i >= 0;) { uint64_t bits = cells_decoded_[i].load(std::memory_order_relaxed); if (bits == 0) continue; do { ABSL_ASSUME(bits != 0); int offset = absl::countr_zero(bits); delete cells_[(i << 6) + offset]; bits &= bits - 1; } while (bits != 0); cells_decoded_[i].store(0, std::memory_order_relaxed); } } cell_cache_.clear(); } size_t EncodedS2ShapeIndex::SpaceUsed() const { // TODO(ericv): Add SpaceUsed() method to S2Shape base class,and include // memory owned by the allocated S2Shapes (here and in S2ShapeIndex). size_t size = sizeof(*this); size += shapes_.capacity() * sizeof(std::atomic); size += cell_ids_.size() * sizeof(std::atomic); // cells_ size += cells_decoded_.capacity() * sizeof(std::atomic); size += cell_cache_.capacity() * sizeof(int); return size; } src/s2/encoded_s2shape_index.h000066400000000000000000000357221524103652300165710ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_ENCODED_S2SHAPE_INDEX_H_ #define S2_ENCODED_S2SHAPE_INDEX_H_ #include #include #include #include #include #include "absl/log/absl_check.h" #include "absl/strings/cord.h" #include "s2/util/coding/coder.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/encoded_s2cell_id_vector.h" #include "s2/encoded_string_vector.h" #include "s2/mutable_s2shape_index.h" #include "s2/s2cell_id.h" #include "s2/s2point.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" // EncodedS2ShapeIndex is an S2ShapeIndex implementation that works directly // with encoded data. Rather than decoding everything in advance, geometry is // decoded incrementally (down to individual edges) as needed. It can be // initialized from a single block of data in nearly constant time (about 1.3 // microseconds per million edges). This saves large amounts of memory and is // also much faster in the common situation where geometric data is loaded // from somewhere, decoded, and then only a single operation is performed on // it. It supports all S2ShapeIndex operations including boolean operations, // measuring distances, etc. // // The speedups can be over 1000x for large geometric objects. For example // vertices and 50,000 loops. If this geometry is represented as an // S2Polygon, then simply decoding it takes ~250ms and building its internal // S2ShapeIndex takes a further ~1500ms. These times are much longer than the // time needed for many operations, e.g. e.g. measuring the distance from the // polygon to one of its vertices takes only about 0.001ms. // // If the same geometry is represented using EncodedLaxPolygonShape and // EncodedS2ShapeIndex, initializing the index takes only 0.005ms. The // distance measuring operation itself takes slightly longer than before // (0.0013ms vs. the original 0.001ms) but the overall time is now much lower // (~0.007ms vs. 1750ms). This is possible because the new classes decode // data lazily (only when it is actually needed) and with fine granularity // (down to the level of individual edges). The overhead associated with this // incremental decoding is small; operations are typically 25% slower compared // to fully decoding the MutableS2ShapeIndex and its underlying shapes. // // EncodedS2ShapeIndex also uses less memory than MutableS2ShapeIndex. The // encoded data is contiguous block of memory that is typically between 4-20% // of the original index size (see MutableS2ShapeIndex::Encode for examples). // Constructing the EncodedS2ShapeIndex uses additional memory, but even so // the total memory usage immediately after construction is typically 25-35% // of the corresponding MutableS2ShapeIndex size. // // Note that MutableS2ShapeIndex will still be faster and use less memory if // you need to decode the entire index. Similarly MutableS2ShapeIndex will be // faster if you plan to execute a large number of operations on it. The main // advantage of EncodedS2ShapeIndex is that it is much faster and uses less // memory when only a small portion of the data needs to be decoded. // // Example code showing how to create an encoded index: // // Encoder encoder; // s2shapeutil::CompactEncodeTaggedShapes(index, encoder); // index.Encode(encoder); // string encoded(encoder.base(), encoder.length()); // Encoded data. // // Example code showing how to use an encoded index: // // Decoder decoder(encoded.data(), encoded.size()); // EncodedS2ShapeIndex index; // index.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder)); // S2ClosestEdgeQuery query(&index); // S2ClosestEdgeQuery::PointTarget target(test_point); // if (query.IsDistanceLessOrEqual(&target, limit)) { // ... // } // // Note that EncodedS2ShapeIndex does not make a copy of the encoded data, and // therefore the client must ensure that this data outlives the // EncodedS2ShapeIndex object. // // There are a number of built-in classes that work with S2ShapeIndex objects. // Generally these classes accept any collection of geometry that can be // represented by an S2ShapeIndex, i.e. any combination of points, polylines, // and polygons. Such classes include: // // - S2ContainsPointQuery: returns the shape(s) that contain a given point. // // - S2ClosestEdgeQuery: returns the closest edge(s) to a given point, edge, // S2CellId, or S2ShapeIndex. // // - S2CrossingEdgeQuery: returns the edge(s) that cross a given edge. // // - S2BooleanOperation: computes boolean operations such as union, // and boolean predicates such as containment. // // - S2ShapeIndexRegion: can be used together with S2RegionCoverer to // approximate geometry as a set of S2CellIds. // // - S2ShapeIndexBufferedRegion: computes approximations that have been // expanded by a given radius. // // EncodedS2ShapeIndex is thread-compatible, meaning that const methods are // thread safe, and non-const methods are not thread safe. The only non-const // method is Minimize(), so if you plan to call Minimize() while other threads // are actively using the index that you must use an external reader-writer // lock such as absl::Mutex to guard access to it. (There is no global state // and therefore each index can be guarded independently.) class EncodedS2ShapeIndex final : public S2ShapeIndex { public: using Options = MutableS2ShapeIndex::Options; using ShapeFactory = S2ShapeIndex::ShapeFactory; // Creates an index that must be initialized by calling Init(). EncodedS2ShapeIndex(); ~EncodedS2ShapeIndex() override; // Initializes the EncodedS2ShapeIndex, returning true on success. // // This method does not decode the S2Shape objects in the index; this is // the responsibility of the client-provided function "shape_factory" // (see s2shapeutil_coding.h). Example usage: // // index.Init(decoder, s2shapeutil::LazyDecodeShapeFactory(decoder)); // // Note that the encoded shape vector must *precede* the encoded S2ShapeIndex // in the Decoder's data buffer in this example. bool Init(Decoder* decoder, const ShapeFactory& shape_factory); // Copies the encoded byte stream into a new encoder. void Encode(Encoder* encoder) const override; const Options& options() const { return options_; } // The number of distinct shape ids in the index. This equals the number of // shapes in the index provided that no shapes have ever been removed. // (Shape ids are not reused.) int num_shape_ids() const override { return shapes_.size(); } // Return a pointer to the shape with the given id. // // REQUIRES: 0 <= id < num_shape_ids() const S2Shape* shape(int id) const override; // Minimizes memory usage by requesting that any data structures that can be // rebuilt should be discarded. This method invalidates all iterators. // // Like all non-const methods, this method is not thread-safe. void Minimize() override; class Iterator final : public IteratorBase { public: // Default constructor; must be followed by a call to Init(). Iterator(); // Constructs an iterator positioned as specified. By default iterators // are unpositioned, since this avoids an extra seek in this situation // where one of the seek methods (such as Locate) is immediately called. // // If you want to position the iterator at the beginning, e.g. in order to // loop through the entire index, do this instead: // // for (EncodedS2ShapeIndex::Iterator it(&index, S2ShapeIndex::BEGIN); // !it.done(); it.Next()) { ... } explicit Iterator(const EncodedS2ShapeIndex* index, InitialPosition pos = UNPOSITIONED); // Initializes an iterator for the given EncodedS2ShapeIndex. void Init(const EncodedS2ShapeIndex* index, InitialPosition pos = UNPOSITIONED); S2CellId id() const override; bool done() const override; const S2ShapeIndexCell& cell() const override; // S2CellIterator API: void Begin() override; void Finish() override; void Next() override; bool Prev() override; void Seek(S2CellId target) override; bool Locate(const S2Point& target) override { return LocateImpl(*this, target); } S2CellRelation Locate(S2CellId target) override { return LocateImpl(*this, target); } std::unique_ptr Clone() const override { return std::make_unique(*this); } private: const EncodedS2ShapeIndex* index_ = nullptr; int32_t cell_pos_; // Current position in the vector of index cells. int32_t num_cells_; }; // Returns the number of bytes currently occupied by the index (including any // unused space at the end of vectors, etc). It has the same thread safety // as the other "const" methods (see introduction). size_t SpaceUsed() const override; protected: std::unique_ptr NewIterator(InitialPosition pos) const override; private: friend class Iterator; // Returns a value indicating that a shape has not been decoded yet. inline static S2Shape* kUndecodedShape() { return reinterpret_cast(1); } // Like std::atomic, but defaults to kUndecodedShape(). class AtomicShape : public std::atomic { public: AtomicShape() : std::atomic(kUndecodedShape()) {} }; S2Shape* GetShape(int id) const; const S2ShapeIndexCell* GetCell(int i) const; bool cell_decoded(int i) const; void set_cell_decoded(int i) const; int max_cell_cache_size() const; std::unique_ptr shape_factory_; // The options specified for this index. Options options_; // The index encoding version. uint8_t version_; // A vector containing all shapes in the index. Initially all shapes are // set to kUndecodedShape(); as shapes are decoded, they are added to the // vector using std::atomic::compare_exchange_strong. mutable std::vector shapes_; // A vector containing the S2CellIds of each cell in the index. s2coding::EncodedS2CellIdVector cell_ids_; // A vector containing the encoded contents of each cell in the index. s2coding::EncodedStringVector encoded_cells_; // A raw array containing the decoded contents of each cell in the index. // Initially all values are *uninitialized memory*. The cells_decoded_ // field below keeps track of which elements are present. mutable std::unique_ptr cells_; // A bit vector indicating which elements of cells_ have been decoded. // All other elements of cells_ contain uninitialized (random) memory. mutable std::vector> cells_decoded_; // In order to minimize destructor time when very few cells of a large // S2ShapeIndex are needed, we keep track of the indices of the first few // cells to be decoded. This lets us avoid scanning the cells_decoded_ // vector when the number of cells decoded is very small. mutable std::vector cell_cache_; // Protects all updates to cells_ and cells_decoded_. mutable SpinLock cells_lock_; EncodedS2ShapeIndex(const EncodedS2ShapeIndex&) = delete; void operator=(const EncodedS2ShapeIndex&) = delete; }; ////////////////// Implementation details follow //////////////////// inline EncodedS2ShapeIndex::Iterator::Iterator( const EncodedS2ShapeIndex* index, InitialPosition pos) { Init(index, pos); } inline void EncodedS2ShapeIndex::Iterator::Init( const EncodedS2ShapeIndex* index, InitialPosition pos) { index_ = index; num_cells_ = index->cell_ids_.size(); cell_pos_ = (pos == BEGIN) ? 0 : num_cells_; } inline S2CellId EncodedS2ShapeIndex::Iterator::id() const { if (done()) { return S2CellId::Sentinel(); } return index_->cell_ids_[cell_pos_]; } inline bool EncodedS2ShapeIndex::Iterator::done() const { return cell_pos_ == num_cells_; } inline const S2ShapeIndexCell& EncodedS2ShapeIndex::Iterator::cell() const { ABSL_DCHECK(!done()); return *index_->GetCell(cell_pos_); } inline void EncodedS2ShapeIndex::Iterator::Begin() { cell_pos_ = 0; } inline void EncodedS2ShapeIndex::Iterator::Finish() { cell_pos_ = num_cells_; } inline void EncodedS2ShapeIndex::Iterator::Next() { ABSL_DCHECK(!done()); ++cell_pos_; } inline bool EncodedS2ShapeIndex::Iterator::Prev() { if (cell_pos_ == 0) { return false; } --cell_pos_; return true; } inline void EncodedS2ShapeIndex::Iterator::Seek(S2CellId target) { cell_pos_ = index_->cell_ids_.lower_bound(target); } inline std::unique_ptr EncodedS2ShapeIndex::NewIterator(InitialPosition pos) const { return std::make_unique(this, pos); } inline const S2Shape* EncodedS2ShapeIndex::shape(int id) const { const S2Shape* shape = shapes_[id].load(std::memory_order_acquire); if (shape != kUndecodedShape()) return shape; return GetShape(id); } // Returns true if the given cell has already been decoded. inline bool EncodedS2ShapeIndex::cell_decoded(int i) const { // cell_decoded(i) uses acquire/release synchronization (see .cc file). uint64_t group_bits = cells_decoded_[i >> 6].load(std::memory_order_acquire); return (group_bits & (1ULL << (i & 63))) != 0; } // Marks the given cell as having been decoded. // REQUIRES: cells_lock_ is held inline void EncodedS2ShapeIndex::set_cell_decoded(int i) const { ABSL_DCHECK(cells_lock_.IsHeld()); // We use memory_order_release for the store operation below to ensure that // cells_decoded(i) sees the most recent value, however we can use // memory_order_relaxed for the load because cells_lock_ is held. std::atomic* group = &cells_decoded_[i >> 6]; uint64_t bits = group->load(std::memory_order_relaxed); group->store(bits | 1ULL << (i & 63), std::memory_order_release); } inline int EncodedS2ShapeIndex::max_cell_cache_size() const { // The cell cache is sized so that scanning decoded_cells_ in the destructor // costs about 30 cycles per decoded cell in the worst case. (This overhead // is acceptable relative to the other costs of decoding each cell.) // // For example, if there are 65,536 cells then we won't need to scan // encoded_cells_ unless we decode at least (65536/2048) == 32 cells. It // takes about 1 cycle per 64 cells to scan encoded_cells_, so that works // out to (65536/64) == 1024 cycles. However this cost is amortized over // the 32 cells decoded, which works out to 32 cycles per cell. return cell_ids_.size() >> 11; } #endif // S2_ENCODED_S2SHAPE_INDEX_H_ src/s2/encoded_s2shape_index_test.cc000066400000000000000000000726111524103652300177640ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_s2shape_index.h" #include #include #include #include #include #include #include #include #include #include "absl/base/call_once.h" #include "absl/flags/flag.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "absl/strings/escaping.h" #include "absl/strings/str_cat.h" #include "s2/util/coding/coder.h" #include "s2/mutable_s2shape_index.h" #include "s2/s1angle.h" #include "s2/s2builder.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_s2polyline_layer.h" #include "s2/s2builderutil_snap_functions.h" #include "s2/s2cap.h" #include "s2/s2cell_id.h" #include "s2/s2closest_edge_query.h" #include "s2/s2coder.h" #include "s2/s2contains_point_query.h" #include "s2/s2edge_distances.h" #include "s2/s2error.h" #include "s2/s2fractal.h" #include "s2/s2latlng.h" #include "s2/s2lax_polygon_shape.h" #include "s2/s2lax_polyline_shape.h" #include "s2/s2loop.h" #include "s2/s2point.h" #include "s2/s2point_vector_shape.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2random.h" #include "s2/s2shape.h" #include "s2/s2shapeutil_coding.h" #include "s2/s2shapeutil_testing.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" #include "s2/thread_testing.h" #include "s2/util/math/matrix3x3.h" #include "s2/util/random/shared_bit_gen.h" using absl::StrCat; using s2builderutil::S2CellIdSnapFunction; using s2builderutil::S2PolylineLayer; using std::make_unique; using std::max; using std::string; using std::unique_ptr; using std::vector; template bool DecodeHomegeneousShapeIndex(EncodedS2ShapeIndex* index, Decoder* decoder) { return index->Init(decoder, s2shapeutil::HomogeneousShapeFactory(decoder)); } template void TestEncodedS2ShapeIndex(const MutableS2ShapeIndex& expected, size_t expected_bytes) { Encoder encoder; s2shapeutil::EncodeHomogeneousShapes(expected, &encoder); size_t shapes_bytes = encoder.length(); expected.Encode(&encoder); EXPECT_EQ(expected_bytes, encoder.length() - shapes_bytes); Decoder decoder(encoder.base(), encoder.length()); EncodedS2ShapeIndex actual; ASSERT_TRUE(DecodeHomegeneousShapeIndex(&actual, &decoder)); EXPECT_EQ(expected.options().max_edges_per_cell(), actual.options().max_edges_per_cell()); s2testing::ExpectEqual(expected, actual); // Make sure that re-encoding the index gives us back the original bytes. Encoder new_encoder; actual.Encode(&new_encoder); EXPECT_EQ(encoder.length() - shapes_bytes, new_encoder.length()); const char* index_base = encoder.base() + shapes_bytes; EXPECT_EQ(memcmp(index_base, new_encoder.base(), new_encoder.length()), 0); } TEST(EncodedS2ShapeIndex, Empty) { MutableS2ShapeIndex index; TestEncodedS2ShapeIndex(index, 4); } TEST(EncodedS2ShapeIndex, OneEdge) { MutableS2ShapeIndex index; index.Add(s2textformat::MakeLaxPolylineOrDie("1:1, 2:2")); TestEncodedS2ShapeIndex(index, 8); } TEST(EncodedS2ShapeIndex, RegularLoops) { struct TestCase { int num_edges; size_t expected_bytes; }; vector test_cases = { {4, 8}, {8, 8}, {16, 16}, {64, 77}, {256, 327}, {4096, 8813}, {65536, 168291}, }; for (const auto& test_case : test_cases) { MutableS2ShapeIndex index; SCOPED_TRACE(StrCat("num_edges = ", test_case.num_edges)); S2Polygon polygon(S2Loop::MakeRegularLoop(S2Point(3, 2, 1).Normalize(), S1Angle::Degrees(0.1), test_case.num_edges)); index.Add(make_unique(polygon)); TestEncodedS2ShapeIndex( index, test_case.expected_bytes); } } #if !defined( __EMSCRIPTEN__) && !(defined(__ANDROID__) && defined(__i386__)) // TODO(b/232496949): This test relies on `mt19937_64` return values because // it tests an exact encoded byte size. Either change it to accept a range // of sizes, or decode and check either the number of shapes, or possibly // the points themselves by resetting the RNG state. TEST(EncodedS2ShapeIndex, OverlappingPointClouds) { std::mt19937_64 bitgen; struct TestCase { int num_shapes, num_points_per_shape; size_t expected_bytes; }; vector test_cases = { {1, 50, 85}, {2, 100, 600}, {4, 100, 1426}, }; S2Cap cap(S2Point(0.1, -0.4, 0.3).Normalize(), S1Angle::Degrees(1)); for (const auto& test_case : test_cases) { MutableS2ShapeIndex index; SCOPED_TRACE(StrCat("num_shapes = ", test_case.num_shapes)); for (int i = 0; i < test_case.num_shapes; ++i) { vector points; for (int j = 0; j < test_case.num_points_per_shape; ++j) { points.push_back(s2random::SamplePoint(bitgen, cap)); } index.Add(make_unique(points)); } TestEncodedS2ShapeIndex( index, test_case.expected_bytes); } } // TODO(b/232496949): This test relies on `mt19937_64` return values. TEST(EncodedS2ShapeIndex, OverlappingPolylines) { std::mt19937_64 bitgen; struct TestCase { int num_shapes, num_shape_edges; size_t expected_bytes; }; vector test_cases = { {2, 50, 128}, {10, 50, 808}, {20, 50, 2499}, }; S2Cap cap(S2Point(-0.2, -0.3, 0.4).Normalize(), S1Angle::Degrees(0.1)); for (const auto& test_case : test_cases) { S1Angle edge_len = 2 * cap.GetRadius() / test_case.num_shape_edges; MutableS2ShapeIndex index; SCOPED_TRACE(StrCat("num_shapes = ", test_case.num_shapes)); for (int i = 0; i < test_case.num_shapes; ++i) { S2Point a = s2random::SamplePoint(bitgen, cap); S2Point b = s2random::Point(bitgen); vector vertices; int n = test_case.num_shape_edges; for (int j = 0; j <= n; ++j) { vertices.push_back(S2::GetPointOnLine(a, b, j * edge_len)); } index.Add(make_unique(vertices)); } TestEncodedS2ShapeIndex( index, test_case.expected_bytes); } } // TODO(b/232496949): This test relies on `mt19937_64` return values. TEST(EncodedS2ShapeIndex, OverlappingLoops) { std::mt19937_64 bitgen; struct TestCase { int num_shapes, max_edges_per_loop; size_t expected_bytes; }; vector test_cases = { {2, 250, 412}, {5, 250, 1208}, {25, 50, 3162}, }; S2Cap cap(S2Point(-0.1, 0.25, 0.2).Normalize(), S1Angle::Degrees(3)); for (const auto& test_case : test_cases) { MutableS2ShapeIndex index; SCOPED_TRACE(StrCat("num_shapes = ", test_case.num_shapes)); for (int i = 0; i < test_case.num_shapes; ++i) { S2Point center = s2random::SamplePoint(bitgen, cap); double radius_fraction = absl::Uniform(bitgen, 0.0, 1.0); // Scale the number of edges so that they are all about the same length // (similar to modeling all geometry at a similar resolution). int num_edges = max(3.0, test_case.max_edges_per_loop * radius_fraction); S2Polygon polygon(S2Loop::MakeRegularLoop( center, cap.GetRadius() * radius_fraction, num_edges)); index.Add(make_unique(polygon)); } TestEncodedS2ShapeIndex( index, test_case.expected_bytes); } } #endif // defined(__EMSCRIPTEN__) // Like S2PolylineLayer, but converts the polyline to an S2LaxPolylineShape // and adds it to an S2ShapeIndex (if the polyline is non-empty). class IndexedLaxPolylineLayer : public S2Builder::Layer { public: using Options = S2PolylineLayer::Options; explicit IndexedLaxPolylineLayer(MutableS2ShapeIndex* index, const Options& options = Options()) : index_(index), polyline_(make_unique()), layer_(polyline_.get(), options) {} GraphOptions graph_options() const override { return layer_.graph_options(); } void Build(const Graph& g, S2Error* error) override { layer_.Build(g, error); if (error->ok() && polyline_->num_vertices() > 0) { index_->Add(make_unique(*polyline_)); } } private: MutableS2ShapeIndex* index_; unique_ptr polyline_; S2PolylineLayer layer_; }; TEST(EncodedS2ShapeIndex, SnappedFractalPolylines) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "SNAPPED_FRACTAL_POLYLINES", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); MutableS2ShapeIndex index; S2Builder builder{S2Builder::Options{S2CellIdSnapFunction()}}; for (int i = 0; i < 5; ++i) { builder.StartLayer(make_unique(&index)); S2Fractal fractal(bitgen); fractal.SetLevelForApproxMaxEdges(3 * 256); auto frame = S2::GetFrame(S2LatLng::FromDegrees(10, i).ToPoint()); auto loop = fractal.MakeLoop(frame, S1Angle::Degrees(0.1)); vector vertices; S2Testing::AppendLoopVertices(*loop, &vertices); S2Polyline polyline(vertices); builder.AddPolyline(polyline); } S2Error error; ASSERT_TRUE(builder.Build(&error)) << error.message(); TestEncodedS2ShapeIndex( index, 8698); } // A test that repeatedly minimizes "index_" in one thread and then reads the // index_ concurrently from several other threads. When all threads have // finished reading, the first thread minimizes the index again. // // Note that Minimize() is non-const and therefore does not need to be tested // concurrently with the const methods. class LazyDecodeTest : public s2testing::ReaderWriterTest { public: LazyDecodeTest() { // We generate one shape per dimension. Each shape has vertices uniformly // distributed across the sphere, and the vertices for each dimension are // different. Having fewer cells in the index is more likely to trigger // race conditions, and so shape 0 has 384 points, shape 1 is a polyline // with 96 vertices, and shape 2 is a polygon with 24 vertices. MutableS2ShapeIndex input; for (int dim = 0; dim < 3; ++dim) { int level = 3 - dim; // See comments above. vector vertices; for (auto id = S2CellId::Begin(level); id != S2CellId::End(level); id = id.next()) { vertices.push_back(id.ToPoint()); } switch (dim) { case 0: input.Add(make_unique(vertices)); break; case 1: input.Add(make_unique(vertices)); break; default: input.Add(make_unique( vector>{std::move(vertices)})); break; } } Encoder encoder; ABSL_CHECK(s2shapeutil::CompactEncodeTaggedShapes(input, &encoder)); input.Encode(&encoder); encoded_.assign(encoder.base(), encoder.length()); Decoder decoder(encoded_.data(), encoded_.size()); ABSL_CHECK( index_.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder))); } void WriteOp() override { index_.Minimize(); } void ReadOp() override { util_random::SharedBitGen bitgen; S2ClosestEdgeQuery query(&index_); for (int iter = 0; iter < 10; ++iter) { S2ClosestEdgeQuery::PointTarget target(s2random::Point(bitgen)); query.FindClosestEdge(&target); } } protected: string encoded_; EncodedS2ShapeIndex index_; }; TEST(EncodedS2ShapeIndex, LazyDecode) { // Ensure that lazy decoding is thread-safe. In other words, make sure that // nothing bad happens when multiple threads call "const" methods that cause // index and/or shape data to be decoded. LazyDecodeTest test; // The number of readers should be large enough so that it is likely that // several readers will be running at once (with a multiple-core CPU). constexpr int kNumReaders = 8; constexpr int kIters = 1000; test.Run(kNumReaders, kIters); } TEST(EncodedS2ShapeIndex, JavaByteCompatibility) { MutableS2ShapeIndex expected; expected.Add(make_unique( s2textformat::MakePolylineOrDie("0:0, 1:1"))); expected.Add(make_unique( s2textformat::MakePolylineOrDie("1:1, 2:2"))); expected.Release(0); // bytes is the encoded data of an S2ShapeIndex with a null shape and a // polyline with one edge. It was derived by base-16 encoding the buffer of // an encoder to which expected was encoded. string bytes = absl::HexStringToBytes( "100036020102000000B4825F3C81FDEF3F27DCF7C958DE913F1EDD892B0BDF913FFC7FB8" "B805F6EF3F28516A6D8FDBA13F27DCF7C958DEA13F28C809010408020010"); Decoder decoder(bytes.data(), bytes.length()); MutableS2ShapeIndex actual; ASSERT_TRUE( actual.Init(&decoder, s2shapeutil::FullDecodeShapeFactory(&decoder))); s2testing::ExpectEqual(expected, actual); } // The number of different polygons used for benchmarking purposes. static constexpr int kNumBenchmarkPolygons = 3; // Returns a pointer to a cached polygon of the given type and snap state. // // REQUIRES: type < kNumBenchmarkPolygons const S2Polygon* GetBenchmarkPolygon(int type, bool snapped) { // Store an array of pointers to cache test polygons. We'll never call // destructors so this doesn't violate the trivial destruction rule. struct CachedPolygon { absl::once_flag once; const S2Polygon* polygon; const S2Polygon* snapped; }; static CachedPolygon cache[kNumBenchmarkPolygons] = {}; ABSL_CHECK_GE(type, 0); ABSL_CHECK_LT(type, kNumBenchmarkPolygons); // Initialize cache entry if it hasn't been done yet. absl::call_once(cache[type].once, [type]() { const string seed_str = StrCat("BENCHMARK_POLYGON", absl::GetFlag(FLAGS_s2_random_seed), type); std::seed_seq seed(seed_str.begin(), seed_str.end()); std::mt19937_64 bitgen(seed); S2Polygon* polygon; switch (type) { case 0: { // A small regular loop. polygon = new S2Polygon(S2Loop::MakeRegularLoop( s2random::Point(bitgen), S2Testing::KmToAngle(10), 8)); break; } case 1: { // A medium-sized fractal loop, e.g. a small natural feature. S2Fractal fractal(bitgen); fractal.SetLevelForApproxMaxEdges(3 * 256); Matrix3x3_d frame = s2random::Frame(bitgen); auto loop = fractal.MakeLoop(frame, S2Testing::KmToAngle(10)); polygon = new S2Polygon(std::move(loop)); break; } case 2: { // A large number of small loops. polygon = new S2Polygon(); S2Testing::ConcentricLoopsPolygon(S2Point(1, 0, 0), 100, 10, polygon); break; } default: ABSL_LOG(FATAL) << "Unsupported benchmark polygon index: " << type; } // Build snapped variant of polygon S2Polygon* snapped = new S2Polygon(); snapped->InitToSnapped(*polygon, S2CellId::kMaxLevel); cache[type].polygon = polygon; cache[type].snapped = snapped; }); // Cache will always be initialized at this point, safe to read values. return snapped ? cache[type].snapped : cache[type].polygon; } // Returns a pointer to a cached polygon specified by the benchmark state. // // REQUIRES: state.range(0) < kNumBenchmarkPolygons const S2Polygon* GetBenchmarkPolygon(const benchmark::State& state) { return GetBenchmarkPolygon(state.range(0), state.range(1)); } // Returns an owning pointer to a polygon specified by the benchmark state. // Since the returned pointer is mutable, polygons are cloned from the cached // values returned by `GetBenchmarkPolygon` // // REQUIRES: state.range(0) < kNumBenchmarkPolygons unique_ptr GetMutableBenchmarkPolygon( const benchmark::State& state) { return unique_ptr(GetBenchmarkPolygon(state)->Clone()); } // Returns a pointer to a lax polygon specified by the benchmark state. // // REQUIRES: state.range(0) < kNumBenchmarkPolygons const S2LaxPolygonShape* GetLaxBenchmarkPolygon(const benchmark::State& state) { // Store an array of pointers to cache test polygons. We'll never call // destructors so this doesn't violate the trivial destruction rule. static absl::once_flag once; static const S2LaxPolygonShape* cache[kNumBenchmarkPolygons][2] = {}; // Construct the lax polygon cache once. absl::call_once(once, []() { for (int type = 0; type < kNumBenchmarkPolygons; type++) { for (int snapped = 0; snapped <= 1; snapped++) { const S2Polygon* polygon = GetBenchmarkPolygon(type, snapped); cache[type][snapped] = new S2LaxPolygonShape(*polygon); } } }); int type = state.range(0); bool snapped = state.range(1); ABSL_CHECK_GE(type, 0); ABSL_CHECK_LT(type, kNumBenchmarkPolygons); // Cache will always be initialized at this point, safe to read values. return cache[type][snapped]; } // Runs the given benchmark for all benchmark polygons using the given value // of the "snapped" parameter. template void BenchmarkArgsSnapped(benchmark::internal::Benchmark* benchmark) { for (int i = 0; i < kNumBenchmarkPolygons; ++i) { benchmark->ArgPair(i, snap); } } // Runs the given benchmark for all benchmark polygons, with and without // snapping (which controls whether the FAST or COMPACT encoding is used). void BenchmarkArgs(benchmark::internal::Benchmark* benchmark) { BenchmarkArgsSnapped(benchmark); BenchmarkArgsSnapped(benchmark); } // Measure the time to build and destruct a MutableS2ShapeIndex. static void BM_MutableIndexBuildDestruct(benchmark::State& state) { auto polygon = GetBenchmarkPolygon(state); state.SetLabel(StrCat("vertices = ", polygon->num_vertices(), ", loops = ", polygon->num_loops())); for (auto _ : state) { MutableS2ShapeIndex index; index.Add(make_unique(polygon)); index.ForceBuild(); } } BENCHMARK(BM_MutableIndexBuildDestruct)->Apply(BenchmarkArgsSnapped); // Measure the time to decode and destruct a MutableS2ShapeIndex. static void BM_MutableIndexDecodeDestruct(benchmark::State& state) { Encoder encoder; { MutableS2ShapeIndex index; index.Add(make_unique(*GetBenchmarkPolygon(state))); ABSL_CHECK(s2shapeutil::FastEncodeTaggedShapes(index, &encoder)); index.Encode(&encoder); } for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); MutableS2ShapeIndex index; ABSL_CHECK( index.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder))); } } BENCHMARK(BM_MutableIndexDecodeDestruct)->Apply(BenchmarkArgsSnapped); // Measure the time to initialize and destruct an EncodedS2ShapeIndex. static void BM_EncodedIndexInitDestruct(benchmark::State& state) { Encoder encoder; { MutableS2ShapeIndex index; index.Add(make_unique(*GetBenchmarkPolygon(state))); ABSL_CHECK(s2shapeutil::FastEncodeTaggedShapes(index, &encoder)); int index_start = encoder.length(); index.Encode(&encoder); Decoder decoder(encoder.base(), encoder.length()); state.SetLabel(StrCat("index_bytes = ", encoder.length() - index_start)); } for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); EncodedS2ShapeIndex index; ABSL_CHECK( index.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder))); } } BENCHMARK(BM_EncodedIndexInitDestruct)->Apply(BenchmarkArgsSnapped); // Measure the time to decode and destruct a snapped/unsnapped S2Polygon. static void BM_S2PolygonDecodeDestructSnapped(benchmark::State& state) { Encoder encoder; GetBenchmarkPolygon(state)->Encode(&encoder); state.SetLabel(StrCat("bytes = ", encoder.length())); for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); S2Polygon polygon; ABSL_CHECK(polygon.Decode(&decoder)); } } BENCHMARK(BM_S2PolygonDecodeDestructSnapped)->Apply(BenchmarkArgs); // Measure the time to fully decode and destruct a snapped/unsnapped // S2LaxPolygonShape. static void BM_LaxPolygonDecodeDestructSnapped( benchmark::State& state) { Encoder encoder; GetLaxBenchmarkPolygon(state)->Encode(&encoder, s2coding::CodingHint::COMPACT); state.SetLabel(StrCat("bytes = ", encoder.length())); for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); S2LaxPolygonShape polygon; ABSL_CHECK(polygon.Init(&decoder)); } } BENCHMARK(BM_LaxPolygonDecodeDestructSnapped)->Apply(BenchmarkArgs); // Measure the time to initialize and destruct a snapped/unsnapped // EncodedS2LaxPolygonShape. static void BM_EncodedPolygonInitDestructSnapped( benchmark::State& state) { Encoder encoder; GetLaxBenchmarkPolygon(state)->Encode(&encoder, s2coding::CodingHint::COMPACT); state.SetLabel(StrCat("bytes = ", encoder.length())); for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); EncodedS2LaxPolygonShape polygon; ABSL_CHECK(polygon.Init(&decoder)); } } BENCHMARK(BM_EncodedPolygonInitDestructSnapped)->Apply(BenchmarkArgs); // Measure the time to access an edge of an S2Polygon::Shape. static void BM_S2PolygonGetEdge(benchmark::State& state) { S2Polygon::OwningShape shape(GetMutableBenchmarkPolygon(state)); int i = 0, num_edges = shape.num_edges(); for (auto _ : state) { (void) shape.edge(i); if (++i == num_edges) i = 0; } } BENCHMARK(BM_S2PolygonGetEdge)->Apply(BenchmarkArgsSnapped); static void BM_LaxPolygonGetEdge(benchmark::State& state) { const S2LaxPolygonShape& shape = *GetLaxBenchmarkPolygon(state); int i = 0, num_edges = shape.num_edges(); for (auto _ : state) { benchmark::DoNotOptimize(shape.edge(i)); if (++i == num_edges) i = 0; } } BENCHMARK(BM_LaxPolygonGetEdge)->Apply(BenchmarkArgsSnapped); // Measure the time to access an edge of a snapped/unsnapped // EncodedS2LaxPolygonShape. static void BM_EncodedPolygonGetEdge(benchmark::State& state) { Encoder encoder; GetLaxBenchmarkPolygon(state)->Encode(&encoder, s2coding::CodingHint::COMPACT); state.SetLabel(StrCat("bytes = ", encoder.length())); Decoder decoder(encoder.base(), encoder.length()); EncodedS2LaxPolygonShape shape; ABSL_CHECK(shape.Init(&decoder)); int i = 0, num_edges = shape.num_edges(); for (auto _ : state) { (void) shape.edge(i); if (++i == num_edges) i = 0; } } BENCHMARK(BM_EncodedPolygonGetEdge)->Apply(BenchmarkArgs); // Measure the time to check whether the polygon contains one of its vertices, // using a MutableS2ShapeIndex containing an S2Polygon::Shape. static void BM_ContainsPointMutableIndexS2Polygon(benchmark::State& state) { auto polygon = GetBenchmarkPolygon(state); MutableS2ShapeIndex index; index.Add(make_unique(polygon)); index.ForceBuild(); int i = 0, num_edges = index.shape(0)->num_edges(); for (auto _ : state) { S2Point test_point = index.shape(0)->edge(i).v0; if (S2ContainsPointQuery(&index).Contains(test_point)) ++i; if ((i += 10) >= num_edges) i = 0; } } BENCHMARK(BM_ContainsPointMutableIndexS2Polygon) ->Apply(BenchmarkArgsSnapped); // Measure the time to check whether the polygon contains one of its vertices, // using an EncodedS2ShapeIndex containing a snapped/unsnapped // EncodedS2LaxPolygonShape. static void BM_ContainsPointEncodedIndexPolygon(benchmark::State& state) { Encoder encoder; { MutableS2ShapeIndex index; index.Add(make_unique(*GetBenchmarkPolygon(state))); ABSL_CHECK(s2shapeutil::CompactEncodeTaggedShapes(index, &encoder)); index.Encode(&encoder); } Decoder decoder(encoder.base(), encoder.length()); EncodedS2ShapeIndex index; ABSL_CHECK( index.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder))); int i = 0, num_edges = index.shape(0)->num_edges(); for (auto _ : state) { S2Point test_point = index.shape(0)->edge(i).v0; if (S2ContainsPointQuery(&index).Contains(test_point)) ++i; if ((i += 10) >= num_edges) { // In theory we should stop benchmark timing for this, but ironically // that throws off the benchmark results. i = 0; index.Minimize(); } } } BENCHMARK(BM_ContainsPointEncodedIndexPolygon)->Apply(BenchmarkArgs); // Measure the time to compute distance from the polygon to one of its // vertices, using a MutableS2ShapeIndex containing an S2Polygon::Shape. static void BM_VertexDistanceMutableIndexS2Polygon(benchmark::State& state) { auto polygon = GetBenchmarkPolygon(state); MutableS2ShapeIndex index; index.Add(make_unique(polygon)); index.ForceBuild(); int i = 0, num_edges = index.shape(0)->num_edges(); for (auto _ : state) { S2ClosestEdgeQuery query(&index); S2Point v0 = index.shape(0)->edge(i).v0; S2Point test_point = (v0 + 1e-4 * S2::Ortho(v0)).Normalize(); S2ClosestEdgeQuery::PointTarget target(test_point); query.GetDistance(&target); if ((i += 10) >= num_edges) i = 0; } } BENCHMARK(BM_VertexDistanceMutableIndexS2Polygon) ->Apply(BenchmarkArgsSnapped); // Measure the time to compute the distance from the polygon to one of its // vertices, using an EncodedS2ShapeIndex containing a snapped/unsnapped // EncodedS2LaxPolygonShape. static void BM_VertexDistanceEncodedIndexPolygon(benchmark::State& state) { Encoder encoder; { MutableS2ShapeIndex index; index.Add(make_unique(*GetBenchmarkPolygon(state))); ABSL_CHECK(s2shapeutil::CompactEncodeTaggedShapes(index, &encoder)); index.Encode(&encoder); } Decoder decoder(encoder.base(), encoder.length()); EncodedS2ShapeIndex index; ABSL_CHECK( index.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder))); int i = 0, num_edges = index.shape(0)->num_edges(); for (auto _ : state) { S2ClosestEdgeQuery query(&index); S2Point v0 = index.shape(0)->edge(i).v0; S2Point test_point = (v0 + 1e-4 * S2::Ortho(v0)).Normalize(); S2ClosestEdgeQuery::PointTarget target(test_point); query.GetDistance(&target); if ((i += 10) >= num_edges) { // In theory we should stop benchmark timing for this, but ironically // that throws off the benchmark results. i = 0; index.Minimize(); } } } BENCHMARK(BM_VertexDistanceEncodedIndexPolygon)->Apply(BenchmarkArgs); // Measure the combined time to decode the snapped/unsnapped polygon, build an // S2ShapeIndex for it, and check whether the polygon contains one of its // vertices. static void BM_DecodePolygonBuildIndexContainsPointSnapped( benchmark::State& state) { Encoder encoder; GetBenchmarkPolygon(state)->Encode(&encoder); for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); S2Polygon polygon; ABSL_CHECK(polygon.Decode(&decoder)); MutableS2ShapeIndex index; index.Add(make_unique(&polygon)); S2ContainsPointQuery query(&index); benchmark::DoNotOptimize(query.Contains(polygon.loop(0)->vertex(0))); } } BENCHMARK(BM_DecodePolygonBuildIndexContainsPointSnapped)->Apply(BenchmarkArgs); // Measure the combined time to decode the snapped/unsnapped polygon and its // S2ShapeIndex, and check whether the polygon contains one of its vertices. static void BM_DecodeIndexAndPolygonContainsPointSnapped( benchmark::State& state) { Encoder encoder; { auto polygon = GetBenchmarkPolygon(state); MutableS2ShapeIndex index; index.Add(make_unique(polygon)); ABSL_CHECK(s2shapeutil::CompactEncodeTaggedShapes(index, &encoder)); index.Encode(&encoder); } for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); MutableS2ShapeIndex index; ABSL_CHECK( index.Init(&decoder, s2shapeutil::FullDecodeShapeFactory(&decoder))); S2ContainsPointQuery query(&index); benchmark::DoNotOptimize(query.Contains(index.shape(0)->edge(0).v0)); } } BENCHMARK(BM_DecodeIndexAndPolygonContainsPointSnapped)->Apply(BenchmarkArgs); // Measure the combined time to initialize encoded versions of the // snapped/unsnapped polygon and its index, and check whether the polygon // contains one of its vertices. static void BM_EncodedIndexAndPolygonContainsPointSnapped( benchmark::State& state) { Encoder encoder; { MutableS2ShapeIndex index; index.Add(make_unique(*GetBenchmarkPolygon(state))); ABSL_CHECK(s2shapeutil::CompactEncodeTaggedShapes(index, &encoder)); index.Encode(&encoder); } for (auto _ : state) { Decoder decoder(encoder.base(), encoder.length()); EncodedS2ShapeIndex index; ABSL_CHECK( index.Init(&decoder, s2shapeutil::LazyDecodeShapeFactory(&decoder))); S2ContainsPointQuery query(&index); benchmark::DoNotOptimize(query.Contains(index.shape(0)->edge(0).v0)); } } BENCHMARK(BM_EncodedIndexAndPolygonContainsPointSnapped)->Apply(BenchmarkArgs); src/s2/encoded_string_vector.cc000066400000000000000000000055441524103652300170620ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_string_vector.h" #include #include #include #include #include "absl/log/absl_check.h" #include "absl/strings/string_view.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/encoded_uint_vector.h" using absl::MakeSpan; using absl::Span; using absl::string_view; using std::string; using std::vector; namespace s2coding { StringVectorEncoder::StringVectorEncoder() = default; void StringVectorEncoder::Encode(Encoder* encoder) { offsets_.push_back(data_.length()); // We don't encode the first element of "offsets_", which is always zero. EncodeUintVector( MakeSpan(offsets_.data() + 1, offsets_.data() + offsets_.size()), encoder); encoder->Ensure(data_.length()); encoder->putn(data_.base(), data_.length()); } void StringVectorEncoder::Encode(Span v, Encoder* encoder) { StringVectorEncoder string_vector; for (const auto& str : v) string_vector.Add(str); string_vector.Encode(encoder); } bool EncodedStringVector::Init(Decoder* decoder) { if (!offsets_.Init(decoder)) return false; if (offsets_.size() > 0) { uint64_t length = offsets_[offsets_.size() - 1]; if (decoder->avail() < length) return false; data_ = absl::string_view(decoder->skip(0), length); decoder->skip(length); } else { data_ = absl::string_view(); } return true; } vector EncodedStringVector::Decode() const { size_t n = size(); vector result(n); uint64_t start = 0; for (size_t i = 0; i < n; ++i) { uint64_t limit = offsets_[i]; // Check bounds, skip invalid values, but continue decoding to provide // consistency between Decode() and operator[]. if (start <= limit && limit <= data_.size()) { result[i] = data_.substr(start, limit - start); } start = limit; } return result; } // The encoding must be identical to StringVectorEncoder::Encode(). void EncodedStringVector::Encode(Encoder* encoder) const { offsets_.Encode(encoder); if (offsets_.size() > 0) { ABSL_DCHECK_EQ(data_.size(), offsets_[offsets_.size() - 1]); encoder->Ensure(data_.size()); encoder->putn(data_.data(), data_.size()); } } } // namespace s2coding src/s2/encoded_string_vector.h000066400000000000000000000130001524103652300167060ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_ENCODED_STRING_VECTOR_H_ #define S2_ENCODED_STRING_VECTOR_H_ #include #include #include #include #include "absl/strings/string_view.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/encoded_uint_vector.h" namespace s2coding { // This class allows an EncodedStringVector to be created by adding strings // incrementally. It also supports adding strings that are the output of // another Encoder. For example, to create a vector of encoded S2Polygons, // you can do this: // // void EncodePolygons(const vector& polygons, Encoder* encoder) { // StringVectorEncoder encoded_polygons; // for (auto polygon : polygons) { // polygon->Encode(encoded_polygons.AddViaEncoder()); // } // encoded_polygons.Encode(encoder); // } class StringVectorEncoder { public: StringVectorEncoder(); // Adds a string to the encoded vector. void Add(absl::string_view str); // Adds a string to the encoded vector by means of the given Encoder. The // string consists of all output added to the encoder before the next call // to any method of this class (after which the encoder is no longer valid). Encoder* AddViaEncoder(); // Appends the EncodedStringVector representation to the given Encoder. // // REQUIRES: "encoder" uses the default constructor, so that its buffer // can be enlarged as necessary by calling Ensure(int). void Encode(Encoder* encoder); // Encodes a vector of strings in a format that can later be decoded as an // EncodedStringVector. // // REQUIRES: "encoder" uses the default constructor, so that its buffer // can be enlarged as necessary by calling Ensure(int). static void Encode(absl::Span v, Encoder* encoder); private: // A vector consisting of the starting offset of each string in the // encoder's data buffer, plus a final entry pointing just past the end of // the last string. std::vector offsets_; Encoder data_; }; // This class represents an encoded vector of strings. Values are decoded // only when they are accessed. This allows for very fast initialization and // no additional memory use beyond the encoded data. The encoded data is not // owned by this class; typically it points into a large contiguous buffer // that contains other encoded data as well. // // This is one of several helper classes that allow complex data structures to // be initialized from an encoded format in constant time and then decoded on // demand. This can be a big performance advantage when only a small part of // the data structure is actually used. class EncodedStringVector { public: // Constructs an uninitialized object; requires Init() to be called. EncodedStringVector() = default; // Initializes the EncodedStringVector. Returns false on errors, leaving // the vector in an unspecified state. // // REQUIRES: The Decoder data buffer must outlive this object. bool Init(Decoder* decoder); // Resets the vector to be empty. void Clear(); // Returns the size of the original vector. size_t size() const; // Returns the string at the given index. absl::string_view operator[](size_t i) const; // Returns a Decoder initialized with the string at the given index. Decoder GetDecoder(size_t i) const; // Returns the entire vector of original strings. Requires that the // data buffer passed to the constructor persists until the result vector is // no longer needed. std::vector Decode() const; // Copies the encoded byte stream to a new encoder. void Encode(Encoder* encoder) const; private: EncodedUintVector offsets_; absl::string_view data_; }; ////////////////// Implementation details follow //////////////////// inline void StringVectorEncoder::Add(absl::string_view str) { offsets_.push_back(data_.length()); data_.Ensure(str.size()); data_.putn(str.data(), str.size()); } inline Encoder* StringVectorEncoder::AddViaEncoder() { offsets_.push_back(data_.length()); return &data_; } inline void EncodedStringVector::Clear() { offsets_.Clear(); data_ = absl::string_view(); } inline size_t EncodedStringVector::size() const { return offsets_.size(); } inline absl::string_view EncodedStringVector::operator[](size_t i) const { // Return an empty decoder if we don't have enough data. if (i >= offsets_.size()) { return absl::string_view(); } uint64_t start = (i == 0) ? 0 : offsets_[i - 1]; uint64_t limit = offsets_[i]; if (start <= limit && limit <= data_.size()) { return data_.substr(start, limit - start); } else { return absl::string_view(); // Corrupt data, return empty string. } } inline Decoder EncodedStringVector::GetDecoder(size_t i) const { return Decoder((*this)[i]); } } // namespace s2coding #endif // S2_ENCODED_STRING_VECTOR_H_ src/s2/encoded_string_vector_test.cc000066400000000000000000000107411524103652300201140ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_string_vector.h" #include #include #include #include #include #include "absl/strings/string_view.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" using absl::string_view; using std::string; using std::vector; namespace s2coding { void TestEncodedStringVector(absl::Span input, size_t expected_bytes) { Encoder encoder; StringVectorEncoder::Encode(input, &encoder); EXPECT_EQ(expected_bytes, encoder.length()); Decoder decoder(encoder.base(), encoder.length()); EncodedStringVector actual; ASSERT_TRUE(actual.Init(&decoder)); vector expected; for (const auto& str : input) { expected.push_back(string_view(str)); } EXPECT_EQ(actual.Decode(), expected); // Check that `EncodedStringVector::Encode` produces the same result as // `StringVectorEncoder::Encode`, as documented. Encoder reencoder; actual.Encode(&reencoder); EXPECT_EQ(string_view(encoder.base(), encoder.length()), string_view(reencoder.base(), reencoder.length())); } TEST(EncodedStringVectorTest, Empty) { TestEncodedStringVector({}, 1); } TEST(EncodedStringVectorTest, EmptyString) { TestEncodedStringVector({""}, 2); } TEST(EncodedStringVectorTest, RepeatedEmptyStrings) { TestEncodedStringVector({"", "", ""}, 4); } TEST(EncodedStringVectorTest, OneString) { TestEncodedStringVector({"apples"}, 8); } TEST(EncodedStringVectorTest, TwoStrings) { TestEncodedStringVector({"fuji", "mutsu"}, 12); } TEST(EncodedStringVectorTest, TwoBigStrings) { TestEncodedStringVector({string(10000, 'x'), string(100000, 'y')}, 110007); } TEST(EncodedStringVectorTest, SubscriptOperator) { const string kInput[] = {"pink lady", "gala"}; Encoder encoder; StringVectorEncoder::Encode(kInput, &encoder); Decoder decoder(encoder.base(), encoder.length()); EncodedStringVector v; ASSERT_TRUE(v.Init(&decoder)); ASSERT_EQ(v.size(), 2); EXPECT_EQ(v[0], "pink lady"); EXPECT_EQ(v[1], "gala"); } TEST(EncodedStringVectorTest, ReInitialize) { const string kInput1[] = {"abcd", "edfg"}; const string kInput2[] = {"hij", "klm", "nop", "qrs"}; const string kInput3[] = {"tu"}; Encoder encoder; Encoder reencoder; EncodedStringVector v; StringVectorEncoder::Encode(kInput1, &encoder); Decoder decoder(encoder.base(), encoder.length()); ASSERT_TRUE(v.Init(&decoder)); ASSERT_EQ(v.size(), 2); EXPECT_EQ(v[0], "abcd"); // Reinitialize with a larger input. encoder.clear(); StringVectorEncoder::Encode(kInput2, &encoder); decoder = Decoder(encoder.base(), encoder.length()); ASSERT_TRUE(v.Init(&decoder)); ASSERT_EQ(v.size(), 4); EXPECT_EQ(v[0], "hij"); v.Encode(&reencoder); EXPECT_EQ(string_view(encoder.base(), encoder.length()), string_view(reencoder.base(), reencoder.length())); // Reinitialize with a smaller input. encoder.clear(); StringVectorEncoder::Encode(kInput3, &encoder); decoder = Decoder(encoder.base(), encoder.length()); ASSERT_TRUE(v.Init(&decoder)); ASSERT_EQ(v.size(), 1); EXPECT_EQ(v[0], "tu"); reencoder.clear(); v.Encode(&reencoder); EXPECT_EQ(string_view(encoder.base(), encoder.length()), string_view(reencoder.base(), reencoder.length())); // Reinitialize with an empty input. encoder.clear(); StringVectorEncoder::Encode({}, &encoder); decoder = Decoder(encoder.base(), encoder.length()); ASSERT_TRUE(v.Init(&decoder)); ASSERT_EQ(v.size(), 0); reencoder.clear(); v.Encode(&reencoder); EXPECT_EQ(string_view(encoder.base(), encoder.length()), string_view(reencoder.base(), reencoder.length())); // Reinitialize with an invalid input. encoder.clear(); decoder = Decoder(encoder.base(), encoder.length()); ASSERT_FALSE(v.Init(&decoder)); } } // namespace s2coding src/s2/encoded_uint_vector.h000066400000000000000000000245401524103652300163720ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_ENCODED_UINT_VECTOR_H_ #define S2_ENCODED_UINT_VECTOR_H_ #include #include #include #include #include #include "absl/base/optimization.h" #include "absl/log/absl_check.h" #include "absl/numeric/bits.h" #include "absl/types/span.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/util/coding/coder.h" #include "s2/util/coding/varint.h" #include "s2/util/endian/endian.h" namespace s2coding { // Encodes a vector of unsigned integers in a format that can later be // decoded as an EncodedUintVector. // // REQUIRES: T is an unsigned integer type. // REQUIRES: 2 <= sizeof(T) <= 8 // REQUIRES: "encoder" uses the default constructor, so that its buffer // can be enlarged as necessary by calling Ensure(int). template void EncodeUintVector(absl::Span v, Encoder* encoder); // This class represents an encoded vector of unsigned integers of type T. // Values are decoded only when they are accessed. This allows for very fast // initialization and no additional memory use beyond the encoded data. // The encoded data is not owned by this class; typically it points into a // large contiguous buffer that contains other encoded data as well. // // This is one of several helper classes that allow complex data structures to // be initialized from an encoded format in constant time and then decoded on // demand. This can be a big performance advantage when only a small part of // the data structure is actually used. // // Values are encoded using a fixed number of bytes per value, where the // number of bytes depends on the largest value present. // // REQUIRES: T is an unsigned integer type. // REQUIRES: 2 <= sizeof(T) <= 8 template class EncodedUintVector { public: static_assert(std::is_unsigned::value, "Unsupported signed integer"); static_assert(sizeof(T) & 0xe, "Unsupported integer length"); // Constructs an uninitialized object; requires Init() to be called. EncodedUintVector() = default; // Initializes the EncodedUintVector. Returns false on errors, leaving the // vector in an unspecified state. // // REQUIRES: The Decoder data buffer must outlive this object. bool Init(Decoder* decoder); // Resets the vector to be empty. void Clear(); // Returns the size of the original vector. size_t size() const; // Returns the element at the given index. T operator[](int i) const; // Returns the index of the first element x such that (x >= target), or // size() if no such element exists. // // REQUIRES: The vector elements are sorted in non-decreasing order. size_t lower_bound(T target) const; // Decodes and returns the entire original vector. std::vector Decode() const; void Encode(Encoder* encoder) const; private: template size_t lower_bound(T target) const; const char* data_; uint32_t size_; uint8_t len_; }; // Encodes an unsigned integer in little-endian format using "length" bytes. // (The client must ensure that the encoder's buffer is large enough.) // // REQUIRES: T is an unsigned integer type. // REQUIRES: 2 <= sizeof(T) <= 8 // REQUIRES: 0 <= length <= sizeof(T) // REQUIRES: value < 256 ** length // REQUIRES: encoder->avail() >= length template void EncodeUintWithLength(T value, int length, Encoder* encoder); // Decodes a variable-length integer consisting of "length" bytes starting at // "ptr" in little-endian format. // // REQUIRES: T is an unsigned integer type. // REQUIRES: 2 <= sizeof(T) <= 8 // REQUIRES: 0 <= length <= sizeof(T) template T GetUintWithLength(const char* ptr, int length); // Decodes and consumes a variable-length integer consisting of "length" bytes // in little-endian format. Returns false if not enough bytes are available. // // REQUIRES: T is an unsigned integer type. // REQUIRES: 2 <= sizeof(T) <= 8 // REQUIRES: 0 <= length <= sizeof(T) template bool DecodeUintWithLength(int length, Decoder* decoder, T* result); ////////////////// Implementation details follow //////////////////// template inline void EncodeUintWithLength(T value, int length, Encoder* encoder) { static_assert(std::is_unsigned::value, "Unsupported signed integer"); static_assert(sizeof(T) & 0xe, "Unsupported integer length"); ABSL_DCHECK(length >= 0 && length <= sizeof(T)); ABSL_DCHECK_GE(encoder->avail(), length); while (--length >= 0) { encoder->put8(value); value >>= 8; } ABSL_DCHECK_EQ(value, 0); } template inline T GetUintWithLength(const char* ptr, int length) { static_assert(std::is_unsigned::value, "Unsupported signed integer"); static_assert(sizeof(T) & 0xe, "Unsupported integer length"); ABSL_DCHECK(length >= 0 && length <= sizeof(T)); // Note that the following code is faster than any of the following: // // - A loop that repeatedly loads and shifts one byte. // - memcpying "length" bytes to a local variable of type T. // - A switch statement that handles each length optimally. // // The following code is slightly faster: // // T mask = (length == 0) ? 0 : ~T{0} >> 8 * (sizeof(T) - length); // return *reinterpret_cast(ptr) & mask; // // However this technique is unsafe because in extremely rare cases it might // access out-of-bounds heap memory. (This can only happen if "ptr" is // within (sizeof(T) - length) bytes of the end of a memory page and the // following page in the address space is unmapped.) if (length & sizeof(T)) { return LittleEndian::Load(ptr); } T x = 0; ptr += length; if (sizeof(T) > 4 && (length & 4)) { x = LittleEndian::Load(ptr -= sizeof(uint32_t)); } if (sizeof(T) > 2 && (length & 2)) { x = (x << 16) + LittleEndian::Load(ptr -= sizeof(uint16_t)); } if (sizeof(T) > 1 && (length & 1)) { x = (x << 8) + static_cast(*--ptr); } return x; } template bool DecodeUintWithLength(int length, Decoder* decoder, T* result) { if (decoder->avail() < static_cast(length)) return false; const char* ptr = decoder->skip(0); *result = GetUintWithLength(ptr, length); decoder->skip(length); return true; } template void EncodeUintVector(absl::Span v, Encoder* encoder) { // The encoding is as follows: // // varint64: (v.size() * sizeof(T)) | (len - 1) // array of v.size() elements ["len" bytes each] // // Note that we don't allow (len == 0) since this would require an extra bit // to encode the length. T one_bits = 1; // Ensures len >= 1. for (auto x : v) one_bits |= x; ABSL_ASSUME(one_bits != 0); int len = ((absl::bit_width(one_bits) - 1) >> 3) + 1; ABSL_DCHECK(len >= 1 && len <= 8); // Note that the multiplication is optimized into a bit shift. encoder->Ensure(Varint::kMax64 + v.size() * len); uint64_t size_len = (uint64_t{v.size()} * sizeof(T)) | (len - 1); encoder->put_varint64(size_len); for (auto x : v) { EncodeUintWithLength(x, len, encoder); } } template bool EncodedUintVector::Init(Decoder* decoder) { uint64_t size_len; if (!decoder->get_varint64(&size_len)) return false; size_ = size_len / sizeof(T); // Optimized into bit shift. len_ = (size_len & (sizeof(T) - 1)) + 1; if (size_ > std::numeric_limits::max() / sizeof(T)) return false; size_t bytes = static_cast(size_) * static_cast(len_); if (decoder->avail() < bytes) return false; data_ = decoder->skip(0); decoder->skip(bytes); return true; } template void EncodedUintVector::Clear() { size_ = 0; data_ = nullptr; } template inline size_t EncodedUintVector::size() const { return size_; } template inline T EncodedUintVector::operator[](int i) const { ABSL_DCHECK(i >= 0 && i < size_); return GetUintWithLength(data_ + i * len_, len_); } template size_t EncodedUintVector::lower_bound(T target) const { static_assert(sizeof(T) & 0xe, "Unsupported integer length"); ABSL_DCHECK(len_ >= 1 && len_ <= sizeof(T)); // TODO(ericv): Consider using the unused 28 bits of "len_" to store the // last result of lower_bound() to be used as a hint. This should help in // common situation where the same element is looked up repeatedly. This // would require declaring the new field (length_lower_bound_hint_) as // mutable std::atomic (accessed using std::memory_order_relaxed) // with a custom copy constructor that resets the hint component to zero. switch (len_) { case 1: return lower_bound<1>(target); case 2: return lower_bound<2>(target); case 3: return lower_bound<3>(target); case 4: return lower_bound<4>(target); case 5: return lower_bound<5>(target); case 6: return lower_bound<6>(target); case 7: return lower_bound<7>(target); case 8: return lower_bound<8>(target); } ABSL_UNREACHABLE(); } template template inline size_t EncodedUintVector::lower_bound(T target) const { size_t lo = 0, hi = size_; while (lo < hi) { size_t mid = (lo + hi) >> 1; T value = GetUintWithLength(data_ + mid * length, length); if (value < target) { lo = mid + 1; } else { hi = mid; } } return lo; } template std::vector EncodedUintVector::Decode() const { std::vector result(size_); for (int i = 0; i < size_; ++i) { result[i] = (*this)[i]; } return result; } template // The encoding must be identical to StringVectorEncoder::Encode(). void EncodedUintVector::Encode(Encoder* encoder) const { uint64_t size_len = (uint64_t{size_} * sizeof(T)) | (len_ - 1); encoder->Ensure(Varint::kMax64 + size_len); encoder->put_varint64(size_len); encoder->putn(data_, size_ * len_); } } // namespace s2coding #endif // S2_ENCODED_UINT_VECTOR_H_ src/s2/encoded_uint_vector_test.cc000066400000000000000000000147001524103652300175640ustar00rootroot00000000000000// Copyright 2018 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/encoded_uint_vector.h" #include #include #include #include #include #include #include #include "absl/log/absl_check.h" #include "s2/util/coding/coder.h" using std::vector; namespace s2coding { // Make sure that this class is compact since it is extensively used. // 16 for 64-bit, 12 for 32-bit. static_assert(sizeof(EncodedUintVector) <= 16, "too big"); template void TestEncodedUintVector(const vector& expected, size_t expected_bytes) { Encoder encoder; EncodeUintVector(expected, &encoder); EXPECT_EQ(expected_bytes, encoder.length()); Decoder decoder(encoder.base(), encoder.length()); EncodedUintVector actual; ASSERT_TRUE(actual.Init(&decoder)); EXPECT_EQ(actual.Decode(), expected); } TEST(EncodedUintVectorTest, Empty) { TestEncodedUintVector(vector{}, 1); } TEST(EncodedUintVectorTest, Zero) { TestEncodedUintVector(vector{0}, 2); } TEST(EncodedUintVectorTest, RepeatedZeros) { TestEncodedUintVector(vector{0, 0, 0}, 4); } TEST(EncodedUintVectorTest, MaxInt) { TestEncodedUintVector(vector{~0ULL}, 9); } TEST(EncodedUintVectorTest, OneByte) { TestEncodedUintVector(vector{0, 255, 1, 254}, 5); } TEST(EncodedUintVectorTest, TwoBytes) { TestEncodedUintVector(vector{0, 255, 256, 254}, 9); } TEST(EncodedUintVectorTest, ThreeBytes) { TestEncodedUintVector(vector{0xffffff, 0x0102, 0, 0x050403}, 13); } TEST(EncodedUintVectorTest, EightBytes) { TestEncodedUintVector(vector{~0ULL, 0, 0x0102030405060708}, 25); } template vector MakeSortedTestVector(int bytes_per_value, int num_values) { ABSL_DCHECK_LE(bytes_per_value, sizeof(T)); T limit_value = ~T{0} >> (8 * (sizeof(T) - bytes_per_value)); vector values; for (int i = 0; i + 1 < num_values; ++i) { values.push_back(limit_value * (static_cast(i) / (num_values - 1))); } // The last value needs special handling since casting it to "double" loses // precision when T == uint64_t. values.push_back(limit_value); ABSL_CHECK(std::is_sorted(values.begin(), values.end())); return values; } template EncodedUintVector MakeEncodedVector(const vector& values, Encoder* encoder) { EncodeUintVector(values, encoder); Decoder decoder(encoder->base(), encoder->length()); EncodedUintVector actual; ABSL_CHECK(actual.Init(&decoder)); return actual; } template void TestLowerBound(int bytes_per_value, int num_values) { auto v = MakeSortedTestVector(bytes_per_value, num_values); Encoder encoder; auto actual = MakeEncodedVector(v, &encoder); for (T x : v) { EXPECT_EQ(std::lower_bound(v.begin(), v.end(), x) - v.begin(), actual.lower_bound(x)); if (x > 0) { EXPECT_EQ(std::lower_bound(v.begin(), v.end(), x - 1) - v.begin(), actual.lower_bound(x - 1)); } } } TEST(EncodedUintVector, LowerBound) { for (int bytes_per_value = 8; bytes_per_value <= 8; ++bytes_per_value) { TestLowerBound(bytes_per_value, 10); if (bytes_per_value <= 4) { TestLowerBound(bytes_per_value, 500); if (bytes_per_value <= 2) { TestLowerBound(bytes_per_value, 100); } } } } TEST(EncodedUintVectorTest, RoundtripEncoding) { vector values{10, 20, 30, 40}; Encoder a_encoder; auto a = MakeEncodedVector(values, &a_encoder); ASSERT_EQ(a.Decode(), values); Encoder b_encoder; a.Encode(&b_encoder); Decoder decoder(b_encoder.base(), b_encoder.length()); EncodedUintVector v2; ASSERT_TRUE(v2.Init(&decoder)); EXPECT_EQ(v2.Decode(), values); } template static void BM_DecodeValue(benchmark::State& state) { const int bytes_per_value = state.range(0); constexpr int kNumValues = 1 << 10; // Must be power of 2. ABSL_DCHECK_EQ(kNumValues & (kNumValues - 1), 0); vector values(kNumValues); for (T& x : values) { for (int i = 0; i < bytes_per_value; ++i) { x = (x << 8) | 0xa5; // Immaterial. } } Encoder encoder; EncodeUintVector(values, &encoder); Decoder decoder(encoder.base(), encoder.length()); EncodedUintVector actual; ABSL_CHECK(actual.Init(&decoder)); int i = 0; for (auto _ : state) { benchmark::DoNotOptimize(actual[i]); i = (i + 1) & (kNumValues - 1); } } BENCHMARK_TEMPLATE(BM_DecodeValue, uint32_t) ->Arg(0) ->Arg(1) ->Arg(2) ->Arg(3) ->Arg(4); BENCHMARK_TEMPLATE(BM_DecodeValue, uint64_t) ->Arg(0) ->Arg(1) ->Arg(2) ->Arg(3) ->Arg(4) ->Arg(5) ->Arg(6) ->Arg(7) ->Arg(8); template static void BM_LowerBound(benchmark::State& state) { const int num_values = state.range(0); const int bytes_per_value = state.range(1); auto values = MakeSortedTestVector(bytes_per_value, num_values); T limit_value = values.back(); Encoder encoder; auto actual = MakeEncodedVector(values, &encoder); T value = 0, delta = 3 * (limit_value / num_values); for (auto _ : state) { benchmark::DoNotOptimize(actual.lower_bound(value)); if ((value += delta) > limit_value) value -= limit_value; } } // Use case: S2LaxPolygonShape::cumulative_vertices. // Stores one cumulative vertex count per loop. BENCHMARK_TEMPLATE(BM_LowerBound, uint32_t) ->ArgPair(10, 2) ->ArgPair(1000, 2) ->ArgPair(1000000, 3) ->ArgPair(1000000, 4); // Use case: EncodedS2ShapeIndex::cell_ids_. // Stores one S2CellId value per cell. BENCHMARK_TEMPLATE(BM_LowerBound, uint64_t) ->ArgPair(10, 1) ->ArgPair(1000, 2) ->ArgPair(100000, 3) ->ArgPair(1000000, 4) ->ArgPair(1000000, 5) ->ArgPair(1000000, 6) ->ArgPair(1000000, 7) ->ArgPair(1000000, 8); } // namespace s2coding src/s2/gmock_matchers.cc000066400000000000000000000634531524103652300155020ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/gmock_matchers.h" #include #include #include #include #include #include #include "absl/log/absl_check.h" #include "absl/strings/string_view.h" #include "s2/s1angle.h" #include "s2/s2debug.h" #include "s2/s2latlng.h" #include "s2/s2latlng_rect.h" #include "s2/s2loop.h" #include "s2/s2point.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2text_format.h" using absl::string_view; using std::string; using std::unique_ptr; using ::testing::MakePolymorphicMatcher; using ::testing::MatchResultListener; using ::testing::PolymorphicMatcher; // Printing methods need to be in the global namespace. void PrintTo(const S2Point& p, std::ostream* os) { *os << s2textformat::ToString(p); } void PrintTo(const S2Polyline& l, std::ostream* os) { *os << s2textformat::ToString(l); } void PrintTo(const S2Polygon& p, std::ostream* os) { *os << s2textformat::ToString(p); } void PrintTo(const S2LatLngRect& r, std::ostream* os) { *os << s2textformat::ToString(r); } void PrintTo(const S2Loop& l, std::ostream* os) { *os << s2textformat::ToString(l); } namespace S2 { namespace { // Returns whether the point is approximately the zero-length vector. bool IsAlmostZeroLength(const S2Point& p) { // Implementation is similar to S2::IsUnitLength. See comments there. // TODO(ericv): Verify if this is actually a reasonable value. return fabs(p.Norm2()) <= 5 * DBL_EPSILON; } } // namespace // S2PointMatcher methods. S2PointMatcher::S2PointMatcher(const S2Point& expected, S1Angle tolerance) : expected_(expected), tolerance_(tolerance) { ABSL_CHECK(!IsAlmostZeroLength(expected)); } bool S2PointMatcher::MatchAndExplain(string_view s, MatchResultListener* listener) const { return MatchAndExplain(s2textformat::MakePointOrDie(s), listener); } bool S2PointMatcher::MatchAndExplain(const S2Point& g, MatchResultListener* listener) const { // S2::ApproxEquals will either check fail (debug mode) to unconditionally // return true if either point is the zero-length vector (default S2Point), so // handle that explicitly. if (IsAlmostZeroLength(g)) { *listener << "point is uninitialized or almost zero"; return false; } if ((tolerance_ == S1Angle::Zero() && expected_ != g) || !S2::ApproxEquals(g, expected_, tolerance_)) { *listener << "angle in degrees: " << S1Angle(g, expected_); return false; } return true; } // S2PolylineMatcher methods. bool S2PolylineMatcher::MatchAndExplain(string_view s, MatchResultListener* listener) const { unique_ptr line = s2textformat::MakePolylineOrDie(s); return MatchAndExplain(*line, listener); } bool S2PolylineMatcher::MatchAndExplain(const S2Polyline& g, MatchResultListener* listener) const { switch (options_.type) { case Options::EQUALS: { if (!expected_->Equals(g)) { *listener << "S2Polylines don't match"; return false; } break; } case Options::APPROX_EQUALS: if (!expected_->ApproxEquals(g, options_.tolerance)) { *listener << "S2Polylines don't match with tolerance in degrees " << options_.tolerance; return false; } break; } return true; } // S2PolylineIdenticalToMatcher methods. S2PolylineIdenticalToMatcher::S2PolylineIdenticalToMatcher( const S2Polyline& expected) : expected_(&expected) {} bool S2PolylineIdenticalToMatcher::MatchAndExplain( const S2Polyline& g, MatchResultListener* listener) const { if (expected_->num_vertices() != g.num_vertices()) { *listener << "whose num_vertices " << g.num_vertices() << " doesn't match " << expected_->num_vertices(); return false; } for (int i = 0; i < expected_->num_vertices(); ++i) { if (expected_->vertex(i) != g.vertex(i)) { *listener << "whose vertex(" << i << ") " << s2textformat::ToString(g.vertex(i)) << " doesn't match " << s2textformat::ToString(expected_->vertex(i)); return false; } } if (expected_->GetRectBound() != g.GetRectBound()) { *listener << "whose GetRectBound() " << s2textformat::ToString(g.GetRectBound()) << " doesn't match " << s2textformat::ToString(expected_->GetRectBound()); return false; } if (expected_->s2debug_override() != g.s2debug_override()) { *listener << "whose s2debug_override() " << (g.s2debug_override() == S2Debug::ALLOW ? "ALLOW" : "DISABLE") << " doesn't match " << (expected_->s2debug_override() == S2Debug::ALLOW ? "ALLOW" : "DISABLE"); return false; } return true; } void S2PolylineIdenticalToMatcher::DescribeTo(::std::ostream* os) const { *os << "is identical to polyline " << s2textformat::ToString(*expected_); } void S2PolylineIdenticalToMatcher::DescribeNegationTo(std::ostream* os) const { *os << "is not identical to polyline " << s2textformat::ToString(*expected_); } // S2PolygonMatcher methods. bool S2PolygonMatcher::MatchAndExplain(string_view s, MatchResultListener* listener) const { unique_ptr polygon = s2textformat::MakePolygonOrDie(s, S2Debug::ALLOW); return MatchAndExplain(*polygon, listener); } bool S2PolygonMatcher::MatchAndExplain(const S2Polygon& g, MatchResultListener* listener) const { switch (options_.type) { case Options::EQUALS: { if (!expected_->Equals(g)) { *listener << "S2Polygons don't match"; return false; } break; } case Options::APPROX_EQUALS: { if (!expected_->ApproxEquals(g, options_.tolerance)) { *listener << "S2Polygons don't match with tolerance in degrees " << options_.tolerance; return false; } break; } case Options::BOUNDARY_EQUALS: { if (!expected_->BoundaryEquals(g)) { *listener << "S2Polygons don't match"; return false; } break; } case Options::BOUNDARY_APPROX_EQUALS: { if (!expected_->BoundaryApproxEquals(g, options_.tolerance)) { *listener << "S2Polygons don't match with tolerance in degrees " << options_.tolerance; return false; } break; } case Options::BOUNDARY_NEAR: { if (!expected_->BoundaryNear(g, options_.tolerance)) { *listener << "S2Polygons don't match with tolerance in degrees " << options_.tolerance; return false; } break; } } return true; } // S2LoopMatcher methods. bool S2LoopMatcher::MatchAndExplain(string_view s, MatchResultListener* listener) const { unique_ptr loop = s2textformat::MakeLoopOrDie(s); return MatchAndExplain(*loop, listener); } bool S2LoopMatcher::MatchAndExplain(const S2Loop& g, MatchResultListener* listener) const { switch (options_.type) { case Options::EQUALS: { if (!expected_->Equals(g)) { *listener << "S2Loops don't match"; return false; } break; } case Options::BOUNDARY_EQUALS: { if (!expected_->BoundaryEquals(g)) { *listener << "S2Loops don't match"; return false; } break; } case Options::BOUNDARY_APPROX_EQUALS: { if (!expected_->BoundaryApproxEquals(g, options_.tolerance)) { *listener << "S2Loops don't match with tolerance in degrees " << options_.tolerance; return false; } break; } case Options::BOUNDARY_NEAR: { if (!expected_->BoundaryNear(g, options_.tolerance)) { *listener << "S2Loops don't match with tolerance in degrees " << options_.tolerance; return false; } break; } } return true; } // S2LoopIdenticalToMatcher methods. S2LoopIdenticalToMatcher::S2LoopIdenticalToMatcher(const S2Loop& expected) : expected_(&expected) {} bool S2LoopIdenticalToMatcher::MatchAndExplain( const S2Loop& g, MatchResultListener* listener) const { if (expected_->depth() != g.depth()) { *listener << "whose depth " << g.depth() << " doesn't match " << expected_->depth(); return false; } if (expected_->num_vertices() != g.num_vertices()) { *listener << "whose num_vertices " << g.num_vertices() << " doesn't match " << expected_->num_vertices(); return false; } for (int i = 0; i < expected_->num_vertices(); ++i) { if (expected_->vertex(i) != g.vertex(i)) { *listener << "whose vertex(" << i << ") " << s2textformat::ToString(g.vertex(i)) << " doesn't match " << s2textformat::ToString(expected_->vertex(i)); return false; } } if (expected_->is_empty() != g.is_empty()) { *listener << "whose is_empty() " << g.is_empty() << " doesn't match " << expected_->is_empty(); return false; } if (expected_->is_full() != g.is_full()) { *listener << "whose is_full() " << g.is_full() << " doesn't match " << expected_->is_full(); return false; } if (expected_->IsNormalized() != g.IsNormalized()) { *listener << "whose IsNormalized() " << g.IsNormalized() << " doesn't match " << expected_->IsNormalized(); return false; } if (expected_->Contains(S2::Origin()) != g.Contains(S2::Origin())) { *listener << "whose Contains(S2::Origin()) " << g.Contains(S2::Origin()) << " doesn't match " << expected_->Contains(S2::Origin()); return false; } if (expected_->GetRectBound() != g.GetRectBound()) { *listener << "whose GetRectBound() " << s2textformat::ToString(g.GetRectBound()) << " doesn't match " << s2textformat::ToString(expected_->GetRectBound()); return false; } if (expected_->s2debug_override() != g.s2debug_override()) { *listener << "whose s2debug_override() " << (g.s2debug_override() == S2Debug::ALLOW ? "ALLOW" : "DISABLE") << " doesn't match " << (expected_->s2debug_override() == S2Debug::ALLOW ? "ALLOW" : "DISABLE"); return false; } return true; } void S2LoopIdenticalToMatcher::DescribeTo(::std::ostream* os) const { *os << "is identical to loop " << s2textformat::ToString(*expected_); } void S2LoopIdenticalToMatcher::DescribeNegationTo(std::ostream* os) const { *os << "is not identical to loop " << s2textformat::ToString(*expected_); } // S2PolygonIdenticalToMatcher methods. S2PolygonIdenticalToMatcher::S2PolygonIdenticalToMatcher( const S2Polygon& expected) : expected_(&expected) {} bool S2PolygonIdenticalToMatcher::MatchAndExplain( const S2Polygon& g, MatchResultListener* listener) const { if (expected_->num_loops() != g.num_loops()) { *listener << "whose num_loops() " << g.num_loops() << " doesn't match " << expected_->num_loops(); return false; } for (int i = 0; i < expected_->num_loops(); ++i) { S2LoopIdenticalToMatcher loop_matcher(*expected_->loop(i)); if (!loop_matcher.MatchAndExplain(*g.loop(i), listener)) { *listener << " in loop " << i; return false; } } if (expected_->GetRectBound() != g.GetRectBound()) { *listener << "whose GetRectBound() " << s2textformat::ToString(g.GetRectBound()) << " doesn't match " << s2textformat::ToString(expected_->GetRectBound()); return false; } if (expected_->s2debug_override() != g.s2debug_override()) { *listener << "whose s2debug_override() " << (g.s2debug_override() == S2Debug::ALLOW ? "ALLOW" : "DISABLE") << " doesn't match " << (expected_->s2debug_override() == S2Debug::ALLOW ? "ALLOW" : "DISABLE"); return false; } return true; } void S2PolygonIdenticalToMatcher::DescribeTo(::std::ostream* os) const { *os << "is identical to polygon " << s2textformat::ToString(*expected_); } void S2PolygonIdenticalToMatcher::DescribeNegationTo(std::ostream* os) const { *os << "is not identical to polygon " << s2textformat::ToString(*expected_); } // S2LatLngRectMatcher methods. bool S2LatLngRectMatcher::MatchAndExplain(string_view s, MatchResultListener* listener) const { S2LatLngRect rect = s2textformat::MakeLatLngRectOrDie(s); return MatchAndExplain(rect, listener); } bool S2LatLngRectMatcher::MatchAndExplain(const S2LatLngRect& g, MatchResultListener* listener) const { switch (options_.type) { case Options::EQUALS: { if (!(expected_ == g)) { *listener << "S2LatLngRects don't match"; return false; } break; } case Options::APPROX_EQUALS: { if (!expected_.ApproxEquals(g, options_.tolerance)) { *listener << "S2LatLngRects don't match with tolerance in degrees " << options_.tolerance; return false; } break; } case Options::APPROX_EQUALS_2: { if (!expected_.ApproxEquals(g, options_.tolerance_lat_lng)) { *listener << "S2LatLngRects don't match with tolerance in degrees " << options_.tolerance_lat_lng; return false; } break; } } return true; } // S2LatLngMatcher methods. bool S2LatLngMatcher::MatchAndExplain(string_view s, MatchResultListener* listener) const { S2LatLng latlng = s2textformat::MakeLatLngOrDie(s); return MatchAndExplain(latlng, listener); } bool S2LatLngMatcher::MatchAndExplain(const S2LatLng& latlng, MatchResultListener* listener) const { switch (options_.type) { case Options::EQUALS: { if (!(expected_ == latlng)) { *listener << "S2LatLngs don't match"; return false; } break; } case Options::APPROX_EQUALS: { if (!expected_.ApproxEquals(latlng, options_.tolerance)) { *listener << "S2LatLngs don't match with tolerance in degrees " << options_.tolerance; return false; } break; } } return true; } // Predefined matchers. // Matchers for S2Points provided as objects. PolymorphicMatcher PointEquals(const S2Point& expected) { return MakePolymorphicMatcher(S2PointMatcher(expected, S1Angle::Zero())); } PolymorphicMatcher PointApproxEquals(const S2Point& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PointMatcher(expected, tolerance)); } // Matchers for S2Points provided as strings. PolymorphicMatcher PointEquals(string_view expected) { return MakePolymorphicMatcher(S2PointMatcher(expected, S1Angle::Zero())); } PolymorphicMatcher PointApproxEquals(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PointMatcher(expected, tolerance)); } // Matchers for S2Polylines provided as objects. PolymorphicMatcher PolylineEquals( const S2Polyline& expected) { return MakePolymorphicMatcher(S2PolylineMatcher( expected, S2PolylineMatcher::Options(S2PolylineMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher PolylineApproxEquals( const S2Polyline& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolylineMatcher( expected, S2PolylineMatcher::Options( S2PolylineMatcher::Options::APPROX_EQUALS, tolerance))); } // Matchers for S2Polylines provided as strings. PolymorphicMatcher PolylineEquals(string_view expected) { return MakePolymorphicMatcher(S2PolylineMatcher( expected, S2PolylineMatcher::Options(S2PolylineMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher PolylineApproxEquals(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolylineMatcher( expected, S2PolylineMatcher::Options( S2PolylineMatcher::Options::APPROX_EQUALS, tolerance))); } PolymorphicMatcher PolylineIdenticalTo( const S2Polyline& expected) { return MakePolymorphicMatcher(S2PolylineIdenticalToMatcher(expected)); } // Matchers for S2Polygons provided as objects. PolymorphicMatcher PolygonEquals(const S2Polygon& expected) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options(S2PolygonMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher PolygonApproxEquals( const S2Polygon& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options( S2PolygonMatcher::Options::APPROX_EQUALS, tolerance))); } PolymorphicMatcher PolygonBoundaryEquals( const S2Polygon& expected) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options(S2PolygonMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero()))); } PolymorphicMatcher PolygonBoundaryApproxEquals( const S2Polygon& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options( S2PolygonMatcher::Options::BOUNDARY_APPROX_EQUALS, tolerance))); } PolymorphicMatcher PolygonBoundaryNear( const S2Polygon& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options( S2PolygonMatcher::Options::BOUNDARY_NEAR, tolerance))); } // Matchers for S2Polygons provided as string. PolymorphicMatcher PolygonEquals(string_view expected) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options(S2PolygonMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher PolygonApproxEquals(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options( S2PolygonMatcher::Options::APPROX_EQUALS, tolerance))); } PolymorphicMatcher PolygonBoundaryEquals( string_view expected) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options(S2PolygonMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero()))); } PolymorphicMatcher PolygonBoundaryApproxEquals( string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options( S2PolygonMatcher::Options::BOUNDARY_APPROX_EQUALS, tolerance))); } PolymorphicMatcher PolygonBoundaryNear(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2PolygonMatcher( expected, S2PolygonMatcher::Options( S2PolygonMatcher::Options::BOUNDARY_NEAR, tolerance))); } PolymorphicMatcher PolygonIdenticalTo( const S2Polygon& expected) { return MakePolymorphicMatcher(S2PolygonIdenticalToMatcher(expected)); } // Matchers for S2Loops provided as objects. PolymorphicMatcher LoopEquals(const S2Loop& expected) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LoopBoundaryEquals(const S2Loop& expected) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LoopBoundaryApproxEquals( const S2Loop& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_APPROX_EQUALS, tolerance))); } PolymorphicMatcher LoopBoundaryNear(const S2Loop& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_NEAR, tolerance))); } PolymorphicMatcher LoopIdenticalTo( const S2Loop& expected) { return MakePolymorphicMatcher(S2LoopIdenticalToMatcher(expected)); } // Matchers for S2Loops provided as string. PolymorphicMatcher LoopEquals(string_view expected) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LoopBoundaryEquals(string_view expected) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LoopBoundaryApproxEquals(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_APPROX_EQUALS, tolerance))); } PolymorphicMatcher LoopBoundaryNear(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LoopMatcher( expected, S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_NEAR, tolerance))); } // Matchers for S2LatLngRect provided as objects. PolymorphicMatcher LatLngRectEquals( const S2LatLngRect& expected) { return MakePolymorphicMatcher(S2LatLngRectMatcher( expected, S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LatLngRectApproxEquals( const S2LatLngRect& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LatLngRectMatcher( expected, S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::APPROX_EQUALS, tolerance))); } PolymorphicMatcher LatLngRectApproxEquals( const S2LatLngRect& expected, S2LatLng tolerance) { return MakePolymorphicMatcher(S2LatLngRectMatcher( expected, S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::APPROX_EQUALS_2, tolerance))); } // Matchers for S2LatLngRect provided as string. PolymorphicMatcher LatLngRectEquals(string_view expected) { return MakePolymorphicMatcher(S2LatLngRectMatcher( expected, S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LatLngRectApproxEquals( string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LatLngRectMatcher( expected, S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::APPROX_EQUALS, tolerance))); } PolymorphicMatcher LatLngRectApproxEquals( string_view expected, S2LatLng tolerance) { return MakePolymorphicMatcher(S2LatLngRectMatcher( expected, S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::APPROX_EQUALS_2, tolerance))); } // Matchers for S2LatLng provided as objects. PolymorphicMatcher LatLngEquals(const S2LatLng& expected) { return MakePolymorphicMatcher(S2LatLngMatcher( expected, S2LatLngMatcher::Options(S2LatLngMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LatLngApproxEquals(const S2LatLng& expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LatLngMatcher( expected, S2LatLngMatcher::Options( S2LatLngMatcher::Options::APPROX_EQUALS, tolerance))); } // Matchers for S2LatLng provided as string. PolymorphicMatcher LatLngEquals(string_view expected) { return MakePolymorphicMatcher(S2LatLngMatcher( expected, S2LatLngMatcher::Options(S2LatLngMatcher::Options::EQUALS, S1Angle::Zero()))); } PolymorphicMatcher LatLngApproxEquals(string_view expected, S1Angle tolerance) { return MakePolymorphicMatcher(S2LatLngMatcher( expected, S2LatLngMatcher::Options( S2LatLngMatcher::Options::APPROX_EQUALS, tolerance))); } } // namespace S2 src/s2/gmock_matchers.h000066400000000000000000000537311524103652300153420ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_GMOCK_MATCHERS_H_ #define S2_GMOCK_MATCHERS_H_ #include #include #include #include #include #include "absl/base/attributes.h" #include "absl/strings/string_view.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s1angle.h" #include "s2/s2latlng.h" #include "s2/s2latlng_rect.h" #include "s2/s2loop.h" #include "s2/s2point.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2text_format.h" // GMock matchers for S2LatLng, S2LatLngRect, S2Point, S2Polygon, S2Polyline, // S2Loop. // // Defines polymorphic matchers that can accept a string representation // of each object or a const reference to the object. See gmock_matchers_test.cc // for additional usage examples. // // ==================== // = S2LatLng = // ==================== // // Matchers: // * LatLngEquals: defined as S2LatLng::operator== // * LatLngApproxEquals: defined as S2LatLng::ApproxEquals // // Examples: // EXPECT_THAT(latlng, S2::LatLngEquals("10:10")); // EXPECT_THAT(latlng, S2::LatLngApproxEquals(expected, // S1Angle::Degrees(0.1))); // // ======================== // = S2LatLngRect = // ======================== // // Matchers: // * LatLngRectEquals: defined as S2LatLngRect::operator== // * LatLngRectApproxEquals: defined as S2LatLngRect::ApproxEquals. Accepts // a single tolerance or individual tolerances for lat and lng. // // Examples: // EXPECT_THAT(rect, S2::LatLngRectEquals(expected)); // EXPECT_THAT(rect, S2::LatLngRectApproxEquals( // "0:0,10:10", S1Angle::Radians(1e-10))); // EXPECT_THAT(rect, S2::LatLngRectApproxEquals( // expected, S2LatLng::FromDegrees(0.1, 0.2))); // // =================== // = S2Point = // =================== // // Matchers: // * PointEquals: exact equality check. // * PointApproxEquals: defined as s2pointutil::ApproxEquals with tolerance // with the exception that the default S2Point is not approximately equal // to anything. Expected value is not permitted to be zero or near zero. // // Examples: // EXPECT_THAT(point, S2::PointEquals("10:10"); // EXPECT_THAT(point, S2::PointApproxEquals( // expected, S1Angle::Radians(1e-10)); // // ===================== // = S2Polygon = // ===================== // // Matchers: // * PolygonEquals: defined as S2Polygon::Equals // * PolygonApproxEquals: defined as S2Polygon::ApproxEquals // * PolygonBoundaryEquals: defined as S2Polygon::BoundaryEquals // * PolygonBoundaryApproxEquals: defined as S2Polygon::BoundaryApproxEquals // * PolygonBoundaryNear: defined as S2Polygon::BoundaryNear // * PolygonIdenticalTo: checks that two polygons are identical, including // their loops, bounds, and debug overrides. // // Examples: // EXPECT_THAT(polygon, S2::PolygonEquals("10:10,10:0,0:0"); // EXPECT_THAT(polygon, S2::PolygonApproxEquals( // expected, S1Angle::Radians(1e-10)); // EXPECT_THAT(polygon, S2::PolygonBoundaryEquals(expected); // EXPECT_THAT(polygon, S2::PolygonBoundaryApproxEquals( // expected, S1Angle::Radians(1e-10)); // EXPECT_THAT(polygon, S2::PolygonBoundaryNear( // expected, S1Angle::Radians(1e-10)); // EXPECT_THAT(polygon, S2::PolygonIdenticalTo(expected)); // // ====================== // = S2Polyline = // ====================== // // Matchers: // * PolylineEquals: defined as S2Polyline::Equals // * PolylineApproxEquals: defined as S2Polyline::ApproxEquals // * PolylineIdenticalTo: checks that two polylines are identical, including // their structure, bounds, and debug overrides. // // Examples: // EXPECT_THAT(line, S2::PolylineEquals(expected)); // EXPECT_THAT(line, S2::PolylineApproxEquals( // "10:10,20:20", S1Angle::Radians(1e-10))); // EXPECT_THAT(line, S2::PolylineIdenticalTo(expected)); // // ================== // = S2Loop = // ================== // // Matchers: // * LoopEquals: defined as S2Loop::Equals // * LoopBoundaryEquals: defined as S2Loop::BoundaryEquals // * LoopBoundaryApproxEquals: defined as S2Loop::BoundaryApproxEquals // * LoopBoundaryNear: defined as S2Loop::BoundaryNear // * LoopIdenticalTo: checks that two loops are identical, including their // structure, bounds, depth, and debug overrides. // // Examples: // EXPECT_THAT(loop, S2::LoopEquals("10:10,10:0,0:0")); // EXPECT_THAT(loop, S2::LoopBoundaryEquals("10:10,10:0,0:0")); // EXPECT_THAT(loop, S2::LoopBoundaryApproxEquals( // expected, S1Angle::Radians(1e-10))); // EXPECT_THAT(loop, S2::LoopBoundaryNear( // expected, S1Angle::Radians(1e-10))); // EXPECT_THAT(loop, S2::LoopIdenticalTo(expected_loop)); // Print methods necessary for gmock to print values of S2Point, S2Polyline, // S2Polygon, and S2LatLngRect. void PrintTo(const S2Point& p, std::ostream* os); void PrintTo(const S2Polyline& l, std::ostream* os); void PrintTo(const S2Polygon& p, std::ostream* os); void PrintTo(const S2LatLngRect& r, std::ostream* os); void PrintTo(const S2Loop& l, std::ostream* os); namespace S2 { // Matcher for S2Point. class S2PointMatcher { public: S2PointMatcher(const S2Point& expected, S1Angle tolerance); S2PointMatcher(absl::string_view expected, S1Angle tolerance) : expected_(s2textformat::MakePointOrDie(expected)), tolerance_(tolerance) {} bool MatchAndExplain(absl::string_view s, ::testing::MatchResultListener* listener) const; // When tolerance_ == S1Angle::Zero() the points will be matched with the // S2Point::operator== method. bool MatchAndExplain(const S2Point& g, ::testing::MatchResultListener* listener) const; void DescribeTo(std::ostream* os) const { *os << "== " << s2textformat::ToString(expected_); } void DescribeNegationTo(std::ostream* os) const { *os << "!= " << s2textformat::ToString(expected_); } private: S2Point expected_; S1Angle tolerance_; }; // Matcher for S2Polyline. class S2PolylineMatcher { public: struct Options { // The types of comparison correspond to methods in S2Polyline. Each type // uses the same name as the corresponding method in S2Polyline. enum ComparisonType { EQUALS, // S2Polyline::Equals APPROX_EQUALS // S2Polyline::ApproxEquals }; Options() = default; Options(ComparisonType a_type, S1Angle a_tolerance) : type(a_type), tolerance(a_tolerance) {} ComparisonType type; S1Angle tolerance; }; S2PolylineMatcher(const S2PolylineMatcher& other) { options_ = other.options_; expected_.reset(other.expected_->Clone()); } S2PolylineMatcher& operator=(const S2PolylineMatcher& other) { options_ = other.options_; expected_.reset(other.expected_->Clone()); return *this; } S2PolylineMatcher(const S2Polyline& expected, Options options) : expected_(expected.Clone()), options_(options) {} S2PolylineMatcher(absl::string_view expected, Options options) : expected_(s2textformat::MakePolylineOrDie(expected)), options_(options) {} virtual ~S2PolylineMatcher() = default; bool MatchAndExplain(absl::string_view s, ::testing::MatchResultListener* listener) const; bool MatchAndExplain(const S2Polyline& g, ::testing::MatchResultListener* listener) const; void DescribeTo(std::ostream* os) const { *os << "== " << s2textformat::ToString(*expected_); } void DescribeNegationTo(std::ostream* os) const { *os << "!= " << s2textformat::ToString(*expected_); } private: std::unique_ptr expected_; Options options_; }; // Matcher that checks that two polylines are identical, including their // structure, bounds, and debug overrides. // // Note: The matcher stores a pointer to the expected polyline, so the expected // polyline must outlive the matcher. class S2PolylineIdenticalToMatcher { public: explicit S2PolylineIdenticalToMatcher( const S2Polyline& expected ABSL_ATTRIBUTE_LIFETIME_BOUND); bool MatchAndExplain(const S2Polyline& g, ::testing::MatchResultListener* listener) const; void DescribeTo(::std::ostream* os) const; void DescribeNegationTo(std::ostream* os) const; private: const S2Polyline* expected_; }; // Matcher for S2Polygon. class S2PolygonMatcher { public: struct Options { // The types of comparison correspond to methods in S2Polygon. Each type // uses the same name as the corresponding method in S2Polygon. enum ComparisonType { EQUALS, // S2Polygon::Equals APPROX_EQUALS, // S2Polygon::ApproxEquals BOUNDARY_EQUALS, // S2Polygon::BoundaryEquals BOUNDARY_APPROX_EQUALS, // S2Polygon::BoundaryApproxEquals BOUNDARY_NEAR // S2Polygon::BoundaryNear }; Options() = default; Options(ComparisonType a_type, S1Angle a_tolerance) : type(a_type), tolerance(a_tolerance) {} ComparisonType type; S1Angle tolerance; }; S2PolygonMatcher(const S2Polygon& expected, Options options) : expected_(expected.Clone()), options_(options) {} S2PolygonMatcher(absl::string_view expected, Options options) : expected_(s2textformat::MakePolygonOrDie(expected, S2Debug::ALLOW)), options_(options) {} S2PolygonMatcher(const S2PolygonMatcher& other) { options_ = other.options_; expected_.reset(other.expected_->Clone()); } S2PolygonMatcher& operator=(const S2PolygonMatcher& other) { options_ = other.options_; expected_.reset(other.expected_->Clone()); return *this; } bool MatchAndExplain(absl::string_view s, ::testing::MatchResultListener* listener) const; bool MatchAndExplain(const S2Polygon& g, ::testing::MatchResultListener* listener) const; void DescribeTo(std::ostream* os) const { *os << "== " << s2textformat::ToString(*expected_); } void DescribeNegationTo(std::ostream* os) const { *os << "!= " << s2textformat::ToString(*expected_); } private: std::unique_ptr expected_; Options options_; }; // Matcher for S2Loop. class S2LoopMatcher { public: struct Options { // The types of comparison correspond to methods in S2Loop. Each type // uses the same name as the corresponding method in S2Loop. enum ComparisonType { EQUALS, // S2Loop::Equals BOUNDARY_EQUALS, // S2Loop::BoundaryEquals BOUNDARY_APPROX_EQUALS, // S2Loop::BoundaryApproxEquals BOUNDARY_NEAR // S2Loop::BoundaryNear }; Options() = default; Options(ComparisonType a_type, S1Angle a_tolerance) : type(a_type), tolerance(a_tolerance) {} ComparisonType type; S1Angle tolerance; }; S2LoopMatcher(const S2Loop& expected, Options options) : expected_(expected.Clone()), options_(options) {} S2LoopMatcher(absl::string_view expected, Options options) : expected_(s2textformat::MakeLoopOrDie(expected)), options_(options) {} S2LoopMatcher(const S2LoopMatcher& other) { options_ = other.options_; expected_.reset(other.expected_->Clone()); } S2LoopMatcher& operator=(const S2LoopMatcher& other) { options_ = other.options_; expected_.reset(other.expected_->Clone()); return *this; } bool MatchAndExplain(absl::string_view s, ::testing::MatchResultListener* listener) const; bool MatchAndExplain(const S2Loop& g, ::testing::MatchResultListener* listener) const; void DescribeTo(std::ostream* os) const { *os << "== " << s2textformat::ToString(*expected_); } void DescribeNegationTo(std::ostream* os) const { *os << "!= " << s2textformat::ToString(*expected_); } private: std::unique_ptr expected_; Options options_; }; // Matcher that checks that two loops are identical, including their // structure, bounds, depth, and debug overrides. class S2LoopIdenticalToMatcher { public: explicit S2LoopIdenticalToMatcher( const S2Loop& expected ABSL_ATTRIBUTE_LIFETIME_BOUND); bool MatchAndExplain(const S2Loop& g, ::testing::MatchResultListener* listener) const; void DescribeTo(::std::ostream* os) const; void DescribeNegationTo(std::ostream* os) const; private: const S2Loop* expected_; }; // Matcher that checks that two polygons are identical, including their // loops, bounds, and debug overrides. // // Note: The matcher stores a pointer to the expected polygon, so the expected // polygon must outlive the matcher. class S2PolygonIdenticalToMatcher { public: explicit S2PolygonIdenticalToMatcher( const S2Polygon& expected ABSL_ATTRIBUTE_LIFETIME_BOUND); bool MatchAndExplain(const S2Polygon& g, ::testing::MatchResultListener* listener) const; void DescribeTo(::std::ostream* os) const; void DescribeNegationTo(std::ostream* os) const; private: const S2Polygon* expected_; }; // Matcher for S2LatLngRect. class S2LatLngRectMatcher { public: struct Options { // The types of comparison correspond to methods in S2LatLngRect. Each type // uses the same name as the corresponding method in S2LatLngRect. enum ComparisonType { EQUALS, // S2LatLngRect::operator== APPROX_EQUALS, // S2LatLngRect::ApproxEquals. // Same tolerance for lat and lng. APPROX_EQUALS_2, // s2LatLngRect::ApproxEquals. // Separate tolerance for lat and lng. }; Options() = default; Options(ComparisonType a_type, S1Angle a_tolerance) : type(a_type), tolerance(a_tolerance) {} Options(ComparisonType a_type, S2LatLng tolerance) : type(a_type), tolerance_lat_lng(tolerance) {} ComparisonType type; S1Angle tolerance; S2LatLng tolerance_lat_lng; }; S2LatLngRectMatcher(const S2LatLngRect& expected, Options options) : expected_(expected), options_(options) {} S2LatLngRectMatcher(absl::string_view expected, Options options) : expected_(s2textformat::MakeLatLngRectOrDie(expected)), options_(options) {} S2LatLngRectMatcher(const S2LatLngRectMatcher& other) { options_ = other.options_; expected_ = other.expected_; } S2LatLngRectMatcher& operator=(const S2LatLngRectMatcher& other) = default; bool MatchAndExplain(absl::string_view s, ::testing::MatchResultListener* listener) const; bool MatchAndExplain(const S2LatLngRect& g, ::testing::MatchResultListener* listener) const; void DescribeTo(std::ostream* os) const { *os << "== " << s2textformat::ToString(expected_); } void DescribeNegationTo(std::ostream* os) const { *os << "!= " << s2textformat::ToString(expected_); } private: S2LatLngRect expected_; Options options_; }; // Matcher for S2LatLng. class S2LatLngMatcher { public: struct Options { // The types of comparison correspond to methods in S2LatLng. Each type // uses the same name as the corresponding method in S2LatLng. enum ComparisonType { EQUALS, // S2LatLng::operator== APPROX_EQUALS, // S2LatLng::ApproxEquals. // Same tolerance for lat and lng. }; Options() = default; Options(ComparisonType a_type, S1Angle a_tolerance) : type(a_type), tolerance(a_tolerance) {} ComparisonType type; S1Angle tolerance; }; S2LatLngMatcher(const S2LatLng& expected, Options options) : expected_(expected), options_(options) {} S2LatLngMatcher(absl::string_view expected, Options options) : expected_(s2textformat::MakeLatLngOrDie(expected)), options_(options) {} S2LatLngMatcher(const S2LatLngMatcher& other) { options_ = other.options_; expected_ = other.expected_; } S2LatLngMatcher& operator=(const S2LatLngMatcher& other) = default; bool MatchAndExplain(absl::string_view s, ::testing::MatchResultListener* listener) const; bool MatchAndExplain(const S2LatLng& g, ::testing::MatchResultListener* listener) const; void DescribeTo(std::ostream* os) const { *os << "== " << s2textformat::ToString(expected_); } void DescribeNegationTo(std::ostream* os) const { *os << "!= " << s2textformat::ToString(expected_); } private: S2LatLng expected_; Options options_; }; // Predefined matchers for S2Point, S2Polyline, S2Polygon, S2Loop, S2LatLngRect. // These matchers can be used in EXPECT_THAT statements. // Matchers for S2Points provided as objects. ::testing::PolymorphicMatcher PointEquals( const S2Point& expected); ::testing::PolymorphicMatcher PointApproxEquals( const S2Point& expected, S1Angle tolerance); // Matchers for S2Points provided as strings. ::testing::PolymorphicMatcher PointEquals( absl::string_view expected); ::testing::PolymorphicMatcher PointApproxEquals( absl::string_view expected, S1Angle tolerance); // Matchers for S2Polylines provided as objects. ::testing::PolymorphicMatcher PolylineEquals( const S2Polyline& expected); ::testing::PolymorphicMatcher PolylineApproxEquals( const S2Polyline& expected, S1Angle tolerance); // Matchers for S2Polylines provided as strings. ::testing::PolymorphicMatcher PolylineEquals( absl::string_view expected); ::testing::PolymorphicMatcher PolylineApproxEquals( absl::string_view expected, S1Angle tolerance); ::testing::PolymorphicMatcher PolylineIdenticalTo( const S2Polyline& expected); // Matchers for S2Polygons provided as objects. ::testing::PolymorphicMatcher PolygonEquals( const S2Polygon& expected); ::testing::PolymorphicMatcher PolygonApproxEquals( const S2Polygon& expected, S1Angle tolerance); ::testing::PolymorphicMatcher PolygonBoundaryEquals( const S2Polygon& expected); ::testing::PolymorphicMatcher PolygonBoundaryApproxEquals( const S2Polygon& expected, S1Angle tolerance); ::testing::PolymorphicMatcher PolygonBoundaryNear( const S2Polygon& expected, S1Angle tolerance); ::testing::PolymorphicMatcher PolygonIdenticalTo( const S2Polygon& expected); // Matchers for S2Polygons provided as string. ::testing::PolymorphicMatcher PolygonEquals( absl::string_view expected); ::testing::PolymorphicMatcher PolygonApproxEquals( absl::string_view expected, S1Angle tolerance); ::testing::PolymorphicMatcher PolygonBoundaryEquals( absl::string_view expected); ::testing::PolymorphicMatcher PolygonBoundaryApproxEquals( absl::string_view expected, S1Angle tolerance); ::testing::PolymorphicMatcher PolygonBoundaryNear( absl::string_view expected, S1Angle tolerance); // Matchers for S2Loops provided as objects. ::testing::PolymorphicMatcher LoopEquals(const S2Loop& expected); ::testing::PolymorphicMatcher LoopBoundaryEquals( const S2Loop& expected); ::testing::PolymorphicMatcher LoopBoundaryApproxEquals( const S2Loop& expected, S1Angle tolerance); ::testing::PolymorphicMatcher LoopBoundaryNear( const S2Loop& expected, S1Angle tolerance); ::testing::PolymorphicMatcher LoopIdenticalTo( const S2Loop& expected); // Matchers for S2Loops provided as string. ::testing::PolymorphicMatcher LoopEquals( absl::string_view expected); ::testing::PolymorphicMatcher LoopBoundaryEquals( absl::string_view expected); ::testing::PolymorphicMatcher LoopBoundaryApproxEquals( absl::string_view expected, S1Angle tolerance); ::testing::PolymorphicMatcher LoopBoundaryNear( absl::string_view expected, S1Angle tolerance); // Matchers for S2LatLngRect provided as objects. ::testing::PolymorphicMatcher LatLngRectEquals( const S2LatLngRect& expected); ::testing::PolymorphicMatcher LatLngRectApproxEquals( const S2LatLngRect& expected, S1Angle tolerance); ::testing::PolymorphicMatcher LatLngRectApproxEquals( const S2LatLngRect& expected, S2LatLng tolerance); // Matchers for S2LatLngRect provided as string. ::testing::PolymorphicMatcher LatLngRectEquals( absl::string_view expected); ::testing::PolymorphicMatcher LatLngRectApproxEquals( absl::string_view expected, S1Angle tolerance); ::testing::PolymorphicMatcher LatLngRectApproxEquals( absl::string_view expected, S2LatLng tolerance); // Matchers for S2LatLng provided as objects. ::testing::PolymorphicMatcher LatLngEquals( const S2LatLng& expected); ::testing::PolymorphicMatcher LatLngApproxEquals( const S2LatLng& expected, S1Angle tolerance = S1Angle::Radians(1e-15)); // Matchers for S2LatLng provided as string. ::testing::PolymorphicMatcher LatLngEquals( absl::string_view expected); ::testing::PolymorphicMatcher LatLngApproxEquals( absl::string_view expected, S1Angle tolerance = S1Angle::Radians(1e-15)); } // namespace S2 #endif // S2_GMOCK_MATCHERS_H_ src/s2/gmock_matchers_test.cc000066400000000000000000000466271524103652300165450ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/gmock_matchers.h" #include #include #include #include #include #include "s2/s1angle.h" #include "s2/s2latlng.h" #include "s2/s2latlng_rect.h" #include "s2/s2point.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2text_format.h" namespace S2 { // Tests that the correct matchers are being invoked. Does not test for // the correctness of the s2 comparison methods, those are assumed to be // correct. using ::s2textformat::MakeLatLngOrDie; using ::s2textformat::MakeLatLngRectOrDie; using ::s2textformat::MakeLoopOrDie; using ::s2textformat::MakePointOrDie; using ::s2textformat::MakePolygonOrDie; using ::s2textformat::MakePolylineOrDie; using std::string; using ::testing::MatchesRegex; using ::testing::Not; using ::testing::StringMatchResultListener; TEST(S2testmatchersTest, PointEquals) { S2Point expected = MakePointOrDie("10:10"); // As object. EXPECT_THAT(s2textformat::MakePointOrDie("10:10"), PointEquals(expected)); // As string. EXPECT_THAT("10:10", PointEquals("10:10")); // Negation. EXPECT_THAT("10.01:10", Not(PointEquals("10:10"))); // Explain. StringMatchResultListener listener; S2PointMatcher m("10:10", S1Angle::Zero()); m.MatchAndExplain("10.01:10", &listener); EXPECT_EQ("angle in degrees: 0.0100000", listener.str()); } TEST(S2testmatchersTest, PointApproxEquals) { S2Point expected = MakePointOrDie("10:10"); // As object. EXPECT_THAT(MakePointOrDie("10:10"), PointApproxEquals(expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10", PointApproxEquals("10:10", S1Angle::Radians(1e-10))); // Negation. EXPECT_THAT("11:10", Not(PointApproxEquals("10:10", S1Angle::Radians(1e-10)))); // Explain. { StringMatchResultListener listener; S2PointMatcher m("11:10", S1Angle::Radians(0.01)); m.MatchAndExplain("10:10", &listener); EXPECT_EQ("angle in degrees: 1.0000000", listener.str()); } // Default (uninitialized) point is not approximately equal to anything. S2Point default_point; EXPECT_THAT(default_point, Not(PointApproxEquals("10:10", S1Angle::Radians(1e-10)))); { StringMatchResultListener listener; S2PointMatcher m("10:10", S1Angle::Radians(0.01)); m.MatchAndExplain(default_point, &listener); EXPECT_EQ("point is uninitialized or almost zero", listener.str()); } // A point represented by a vector that is almost the zero-vector should also // not equal anything. S2Point nearly_zero_vector(std::numeric_limits::min(), std::numeric_limits::min(), std::numeric_limits::min()); EXPECT_THAT(nearly_zero_vector, Not(PointApproxEquals("10:10", S1Angle::Radians(1e-10)))); } TEST(S2testmatchersTest, PolylineEquals) { std::unique_ptr expected = MakePolylineOrDie("10:10,20:20"); std::unique_ptr value = MakePolylineOrDie("10:10,20:20"); // As object. EXPECT_THAT(*value, PolylineEquals(*expected)); // As string. EXPECT_THAT("10:10,20:20", PolylineEquals("10:10,20:20")); // Negation. EXPECT_THAT("10:10,5:5", Not(PolylineEquals("10:10,20:20"))); // Explain. StringMatchResultListener listener; S2PolylineMatcher m("10:10,20:20", S2PolylineMatcher::Options( S2PolylineMatcher::Options::EQUALS, S1Angle::Zero())); m.MatchAndExplain("10:10,5:5", &listener); EXPECT_EQ("S2Polylines don't match", listener.str()); } TEST(S2testmatchersTest, PolylineApproxEquals) { std::unique_ptr expected = MakePolylineOrDie("10:10,20:20"); std::unique_ptr value = MakePolylineOrDie("10:10,20:20"); // As object. EXPECT_THAT(*value, PolylineApproxEquals(*expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10,20:20", PolylineApproxEquals("10:10,20:20", S1Angle::Radians(1e-10))); // Negation. EXPECT_THAT("10:10,5:5", Not(PolylineApproxEquals("10:10,20:20", S1Angle::Radians(1e-10)))); // Explain. StringMatchResultListener listener; S2PolylineMatcher m( "10:10,20:20", S2PolylineMatcher::Options(S2PolylineMatcher::Options::APPROX_EQUALS, S1Angle::Degrees(0.1))); m.MatchAndExplain("10:10,5:5", &listener); EXPECT_EQ("S2Polylines don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, PolylineIdenticalTo) { auto expected = MakePolylineOrDie("10:10,20:20"); auto value = MakePolylineOrDie("10:10,20:20"); // As object. EXPECT_THAT(*value, PolylineIdenticalTo(*expected)); // Negation. EXPECT_THAT(*MakePolylineOrDie("10:10,20:21"), Not(PolylineIdenticalTo(*expected))); // Explain. ::testing::StringMatchResultListener listener; S2PolylineIdenticalToMatcher m(*expected); m.MatchAndExplain(*MakePolylineOrDie("10:10,20:21"), &listener); EXPECT_THAT(listener.str(), MatchesRegex("whose vertex\\(1\\) .* doesn't match .*")); } TEST(S2testmatchersTest, PolygonEquals) { std::unique_ptr expected = MakePolygonOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakePolygonOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, PolygonEquals(*expected)); // As string. EXPECT_THAT("10:10,10:0,0:0", PolygonEquals("10:10,10:0,0:0")); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(PolygonEquals("10:10,10:0,0:1"))); // Explain. StringMatchResultListener listener; S2PolygonMatcher m("10:10,10:0,0:0", S2PolygonMatcher::Options( S2PolygonMatcher::Options::EQUALS, S1Angle::Zero())); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Polygons don't match", listener.str()); } TEST(S2testmatchersTest, PolygonApproxEquals) { std::unique_ptr expected = MakePolygonOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakePolygonOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, PolygonApproxEquals(*expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10,10:0,0:0", PolygonApproxEquals("10:10,10:0,0:0", S1Angle::Degrees(0.1))); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(PolygonApproxEquals( "10:10,10:0,0:1", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2PolygonMatcher m( "10:10,10:0,0:0", S2PolygonMatcher::Options(S2PolygonMatcher::Options::APPROX_EQUALS, S1Angle::Degrees(0.1))); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Polygons don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, PolygonBoundaryEquals) { std::unique_ptr expected = MakePolygonOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakePolygonOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, PolygonBoundaryEquals(*expected)); // As string. EXPECT_THAT("10:10,10:0,0:0", PolygonBoundaryEquals("10:10,10:0,0:0")); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(PolygonBoundaryEquals("10:10,10:0,0:1"))); // Explain. StringMatchResultListener listener; S2PolygonMatcher m( "10:10,10:0,0:0", S2PolygonMatcher::Options(S2PolygonMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero())); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Polygons don't match", listener.str()); } TEST(S2testmatchersTest, PolygonBoundaryApproxEquals) { std::unique_ptr expected = MakePolygonOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakePolygonOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, PolygonBoundaryApproxEquals(*expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10,10:0,0:0", PolygonBoundaryApproxEquals( "10:10,10:0,0:0", S1Angle::Radians(1e-10))); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(PolygonBoundaryApproxEquals( "10:10,10:0,0:1", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2PolygonMatcher m("10:10,10:0,0:0", S2PolygonMatcher::Options( S2PolygonMatcher::Options::BOUNDARY_APPROX_EQUALS, S1Angle::Degrees(0.1))); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Polygons don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, PolygonBoundaryNear) { std::unique_ptr expected = MakePolygonOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakePolygonOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, PolygonBoundaryNear(*expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10,10:0,0:0", PolygonBoundaryNear("10:10,10:0,0:0", S1Angle::Radians(1e-10))); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(PolygonBoundaryNear( "10:10,10:0,0:1", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2PolygonMatcher m( "10:10,10:0,0:0", S2PolygonMatcher::Options(S2PolygonMatcher::Options::BOUNDARY_NEAR, S1Angle::Degrees(0.1))); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Polygons don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, LoopEquals) { std::unique_ptr expected = MakeLoopOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakeLoopOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, LoopEquals(*expected)); // As string. EXPECT_THAT("10:10,10:0,0:0", LoopEquals("10:10,10:0,0:0")); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(LoopEquals("10:10,10:0,0:1"))); // Explain. StringMatchResultListener listener; S2LoopMatcher m( "10:10,10:0,0:0", S2LoopMatcher::Options(S2LoopMatcher::Options::EQUALS, S1Angle::Zero())); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Loops don't match", listener.str()); } TEST(S2testmatchersTest, LoopBoundaryEquals) { std::unique_ptr expected = MakeLoopOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakeLoopOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, LoopBoundaryEquals(*expected)); // As string. EXPECT_THAT("10:10,10:0,0:0", LoopBoundaryEquals("10:10,10:0,0:0")); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(LoopBoundaryEquals("10:10,10:0,0:1"))); // Explain. StringMatchResultListener listener; S2LoopMatcher m("10:10,10:0,0:0", S2LoopMatcher::Options( S2LoopMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero())); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Loops don't match", listener.str()); } TEST(S2testmatchersTest, LoopBoundaryEqualsRotatedVertices) { string expected_str = "10:10,10:0,0:0"; std::unique_ptr expected = MakeLoopOrDie(expected_str); std::unique_ptr value = MakeLoopOrDie("10:0,0:0,10:10"); // As object. EXPECT_THAT(*value, LoopBoundaryEquals(*expected)); // As string. EXPECT_THAT("10:10,10:0,0:0", LoopBoundaryEquals(expected_str)); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(LoopBoundaryEquals("10:10,10:0,0:1"))); // Explain. StringMatchResultListener listener; S2LoopMatcher m("10:10,10:0,0:0", S2LoopMatcher::Options( S2LoopMatcher::Options::BOUNDARY_EQUALS, S1Angle::Zero())); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Loops don't match", listener.str()); } TEST(S2testmatchersTest, LoopBoundaryApproxEquals) { std::unique_ptr expected = MakeLoopOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakeLoopOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, LoopBoundaryApproxEquals(*expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10,10:0,0:0", LoopBoundaryApproxEquals( "10:10,10:0,0:0", S1Angle::Radians(1e-10))); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(LoopBoundaryApproxEquals( "10:10,10:0,0:1", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2LoopMatcher m( "10:10,10:0,0:0", S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_APPROX_EQUALS, S1Angle::Degrees(0.1))); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Loops don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, LoopBoundaryNear) { std::unique_ptr expected = MakeLoopOrDie("10:10,10:0,0:0"); std::unique_ptr value = MakeLoopOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, LoopBoundaryNear(*expected, S1Angle::Radians(1e-10))); // As string. EXPECT_THAT("10:10,10:0,0:0", LoopBoundaryNear("10:10,10:0,0:0", S1Angle::Radians(1e-10))); // Negation. EXPECT_THAT("10:10,10:0,0:0", Not(LoopBoundaryNear("10:10,10:0,0:1", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2LoopMatcher m("10:10,10:0,0:0", S2LoopMatcher::Options(S2LoopMatcher::Options::BOUNDARY_NEAR, S1Angle::Degrees(0.1))); m.MatchAndExplain("10:10,10:0,0:1", &listener); EXPECT_EQ("S2Loops don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, LoopIdenticalTo) { auto expected = MakeLoopOrDie("10:10,10:0,0:0"); auto value = MakeLoopOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, LoopIdenticalTo(*expected)); // Negation. EXPECT_THAT(*MakeLoopOrDie("10:10,10:0,0:1"), Not(LoopIdenticalTo(*expected))); // Explain. ::testing::StringMatchResultListener listener; S2LoopIdenticalToMatcher m(*expected); m.MatchAndExplain(*MakeLoopOrDie("10:10,10:0,0:1"), &listener); EXPECT_THAT(listener.str(), MatchesRegex("whose vertex\\(2\\) .* doesn't match .*")); } TEST(S2testmatchersTest, PolygonIdenticalTo) { auto expected = MakePolygonOrDie("10:10,10:0,0:0"); auto value = MakePolygonOrDie("10:10,10:0,0:0"); // As object. EXPECT_THAT(*value, PolygonIdenticalTo(*expected)); // Negation. EXPECT_THAT(*MakePolygonOrDie("10:10,10:0,0:1"), Not(PolygonIdenticalTo(*expected))); // Explain. ::testing::StringMatchResultListener listener; S2PolygonIdenticalToMatcher m(*expected); m.MatchAndExplain(*MakePolygonOrDie("10:10,10:0,0:1"), &listener); EXPECT_THAT( listener.str(), MatchesRegex("whose vertex\\(2\\) .* doesn't match .* in loop 0")); } TEST(S2testmatchersTest, LatLngRectEquals) { S2LatLngRect expected = MakeLatLngRectOrDie("0:0,10:10"); S2LatLngRect value = MakeLatLngRectOrDie("0:0,10:10"); // As object. EXPECT_THAT(value, LatLngRectEquals(expected)); // As string. EXPECT_THAT("0:0,10:10", LatLngRectEquals("0:0,10:10")); // Negation. EXPECT_THAT("0:0,10:10", Not(LatLngRectEquals("0:0,11:10"))); // Explain. StringMatchResultListener listener; S2LatLngRectMatcher m( "0:0,10:10", S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::EQUALS, S1Angle::Zero())); m.MatchAndExplain("0:0,11:10", &listener); EXPECT_EQ("S2LatLngRects don't match", listener.str()); } TEST(S2testmatchersTest, LatLngRectApproxEquals) { S2LatLngRect expected = MakeLatLngRectOrDie("0:0,10:10"); S2LatLngRect value = MakeLatLngRectOrDie("0:0,10:10"); // As object. EXPECT_THAT(value, LatLngRectApproxEquals(expected, S1Angle::Degrees(0.1))); // As string. EXPECT_THAT("0:0,10:10", LatLngRectApproxEquals("0:0,10:10", S1Angle::Degrees(0.1))); // Negation. EXPECT_THAT("0:0,10:10", Not(LatLngRectApproxEquals("0:0,11:10", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2LatLngRectMatcher m( "0:0,10:10", S2LatLngRectMatcher::Options(S2LatLngRectMatcher::Options::APPROX_EQUALS, S1Angle::Degrees(0.1))); m.MatchAndExplain("0:0,11:10", &listener); EXPECT_EQ("S2LatLngRects don't match with tolerance in degrees 0.1000000", listener.str()); } TEST(S2testmatchersTest, LatLngRectApproxEquals2) { S2LatLngRect expected = MakeLatLngRectOrDie("0:0,10:10"); S2LatLngRect value = MakeLatLngRectOrDie("0:0,10:10"); S2LatLng tolerance = S2LatLng::FromDegrees(0.1, 0.2); // As object. EXPECT_THAT(value, LatLngRectApproxEquals(expected, tolerance)); // As string. EXPECT_THAT("0:0,10:10", LatLngRectApproxEquals("0:0,10:10", tolerance)); // Negation. EXPECT_THAT("0:0,10:10", Not(LatLngRectApproxEquals("0:0,11:10", tolerance))); // Explain. StringMatchResultListener listener; S2LatLngRectMatcher m( "0:0,10:10", S2LatLngRectMatcher::Options( S2LatLngRectMatcher::Options::APPROX_EQUALS_2, tolerance)); m.MatchAndExplain("0:0,11:10", &listener); EXPECT_EQ( "S2LatLngRects don't match with tolerance in degrees [0.1000000, " "0.2000000]", listener.str()); } TEST(S2testmatchersTest, LatLngEquals) { S2LatLng expected = MakeLatLngOrDie("10:10"); S2LatLng value = MakeLatLngOrDie("10:10"); // As object. EXPECT_THAT(value, LatLngEquals(expected)); // As string. EXPECT_THAT("10:10", LatLngEquals("10:10")); // Negation. EXPECT_THAT("10:10", Not(LatLngEquals("11:10"))); // Explain. StringMatchResultListener listener; S2LatLngMatcher m("10:10", S2LatLngMatcher::Options(S2LatLngMatcher::Options::EQUALS, S1Angle::Zero())); m.MatchAndExplain("11:10", &listener); EXPECT_EQ("S2LatLngs don't match", listener.str()); } TEST(S2testmatchersTest, LatLngApproxEquals) { S2LatLng expected = MakeLatLngOrDie("10:10"); S2LatLng value = MakeLatLngOrDie("10:10"); // As object. EXPECT_THAT(value, LatLngApproxEquals(expected, S1Angle::Degrees(0.1))); // As string, testing tolerances in both directions EXPECT_THAT("10.095:9.95", LatLngApproxEquals("10:10", S1Angle::Degrees(0.1))); EXPECT_THAT("9.95:10.095", LatLngApproxEquals("10:10", S1Angle::Degrees(0.1))); // Negation. EXPECT_THAT("10:10", Not(LatLngApproxEquals("11:10", S1Angle::Degrees(0.1)))); // Explain. StringMatchResultListener listener; S2LatLngMatcher m( "10:10", S2LatLngMatcher::Options(S2LatLngMatcher::Options::APPROX_EQUALS, S1Angle::Degrees(0.1))); m.MatchAndExplain("11:10", &listener); EXPECT_EQ("S2LatLngs don't match with tolerance in degrees 0.1000000", listener.str()); } } // namespace S2 src/s2/id_set_lexicon.cc000066400000000000000000000051051524103652300154720ustar00rootroot00000000000000// Copyright 2016 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/id_set_lexicon.h" #include #include #include #include #include "absl/log/absl_check.h" #include "s2/sequence_lexicon.h" using std::vector; IdSetLexicon::IdSetLexicon() = default; IdSetLexicon::~IdSetLexicon() = default; // We define the copy/move constructors and assignment operators explicitly // in order to avoid copying/moving the temporary storage vector "tmp_". IdSetLexicon::IdSetLexicon(const IdSetLexicon& x) : id_sets_(x.id_sets_) { } IdSetLexicon::IdSetLexicon(IdSetLexicon&& x) noexcept : id_sets_(std::move(x.id_sets_)) {} IdSetLexicon& IdSetLexicon::operator=(const IdSetLexicon& x) { id_sets_ = x.id_sets_; return *this; } IdSetLexicon& IdSetLexicon::operator=(IdSetLexicon&& x) noexcept { id_sets_ = std::move(x.id_sets_); return *this; } void IdSetLexicon::Clear() { id_sets_.Clear(); } int32_t IdSetLexicon::AddInternal(vector* ids) { if (ids->empty()) { // Empty sets have a special id chosen not to conflict with other ids. return kEmptySetId; } else if (ids->size() == 1) { // Singleton sets are represented by their element. return (*ids)[0]; } else { // Canonicalize the set by sorting and removing duplicates. std::sort(ids->begin(), ids->end()); ids->erase(std::unique(ids->begin(), ids->end()), ids->end()); // After eliminating duplicates, we may now have a singleton. if (ids->size() == 1) return (*ids)[0]; // Non-singleton sets are represented by the bitwise complement of the id // returned by SequenceLexicon. return ~id_sets_.Add(*ids); } } IdSetLexicon::IdSet IdSetLexicon::id_set(int32_t set_id) const { if (set_id >= 0) { return IdSet(set_id); } else if (set_id == kEmptySetId) { return IdSet(); } else { auto sequence = id_sets_.sequence(~set_id); ABSL_DCHECK_NE(0, sequence.size()); return IdSet(&*sequence.begin(), &*sequence.begin() + sequence.size()); } } src/s2/id_set_lexicon.h000066400000000000000000000156531524103652300153450ustar00rootroot00000000000000// Copyright 2016 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_ID_SET_LEXICON_H_ #define S2_ID_SET_LEXICON_H_ #include #include #include #include #include #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/sequence_lexicon.h" // IdSetLexicon is a class for compactly representing sets of non-negative // integers such as array indices ("id sets"). It is especially suitable when // either (1) there are many duplicate sets, or (2) there are many singleton // or empty sets. See also ValueLexicon and SequenceLexicon. // // Each distinct id set is mapped to a 32-bit integer. Empty and singleton // sets take up no additional space whatsoever; the set itself is represented // by the unique id assigned to the set. Sets of size 2 or more occupy about // 11 bytes per set plus 4 bytes per element (as compared to 24 bytes per set // plus 4 bytes per element for std::vector). Duplicate sets are // automatically eliminated. Note also that id sets are referred to using // 32-bit integers rather than 64-bit pointers. // // This class is especially useful in conjunction with ValueLexicon. For // example, suppose that you want to label objects with a set of strings. You // could use a ValueLexicon to map the strings to "label ids" (32-bit // integers), and then use IdSetLexicon to map each set of labels to a "label // set id". Each reference to that label set then takes up only 4 bytes. // // Example usage: // // ValueLexicon labels_; // IdSetLexicon label_sets_; // // int32_t GetLabelSet(const vector& label_strings) { // vector label_ids; // for (const auto& str : label_strings) { // label_ids.push_back(labels_.Add(str)); // } // return label_sets_.Add(label_ids); // } // // int label_set_id = GetLabelSet(...); // for (auto id : label_sets_.id_set(label_set_id)) { // ABSL_LOG(INFO) << id; // } // // This class is similar to SequenceLexicon, except: // // 1. Empty and singleton sets are represented implicitly; they use no space. // 2. Sets are represented rather than sequences; values are reordered to be in // sorted order, and duplicates are removed. // 3. The values must be 32-bit non-negative integers (only). class IdSetLexicon { public: IdSetLexicon(); ~IdSetLexicon(); // IdSetLexicon is movable and copyable. IdSetLexicon(const IdSetLexicon&); IdSetLexicon& operator=(const IdSetLexicon&); IdSetLexicon(IdSetLexicon&&) noexcept; IdSetLexicon& operator=(IdSetLexicon&&) noexcept; // Clears all data from the lexicon. void Clear(); // Add the given set of integers to the lexicon if it is not already // present, and return the unique id for this set. "begin" and "end" are // forward iterators over a sequence of values that can be converted to // non-negative 32-bit integers. The values are automatically sorted and // duplicates are removed. Returns a signed integer representing this set. // // REQUIRES: All values in [begin, end) are non-negative 32-bit integers. template int32_t Add(FwdIterator begin, FwdIterator end); // Add the given set of integers to the lexicon if it is not already // present, and return the unique id for this set. This is a convenience // method equivalent to Add(std::begin(container), std::end(container)). template int32_t Add(const Container& container); // Convenience method that returns the unique id for a singleton set. // Note that because singleton sets take up no space, this method is // const. Equivalent to calling Add(&id, &id + 1). int32_t AddSingleton(int32_t id) const; // Convenience method that returns the unique id for the empty set. Note // that because the empty set takes up no space and has a fixed id, this // method is static. Equivalent to calling Add() with an empty container. static int32_t EmptySetId(); // Iterator type; please treat this as an opaque forward iterator. using Iterator = const int32_t*; // This class represents a set of integers stored in the IdSetLexicon. class IdSet { public: using value_type = const int32_t; Iterator begin() const; Iterator end() const; size_t size() const; private: friend class IdSetLexicon; IdSet(); IdSet(Iterator begin, Iterator end); explicit IdSet(int32_t singleton_id); Iterator begin_, end_; int32_t singleton_id_; }; // Return the set of integers corresponding to an id returned by Add(). IdSet id_set(int32_t set_id) const; private: // Choose kEmptySetId to be the last id that will ever be generated. // (Non-negative ids are reserved for singleton sets.) static constexpr int32_t kEmptySetId = std::numeric_limits::min(); int32_t AddInternal(std::vector* ids); SequenceLexicon id_sets_; std::vector tmp_; // temporary storage used during Add() }; ////////////////// Implementation details follow //////////////////// inline IdSetLexicon::Iterator IdSetLexicon::IdSet::begin() const { return begin_; } inline IdSetLexicon::Iterator IdSetLexicon::IdSet::end() const { return end_; } inline size_t IdSetLexicon::IdSet::size() const { return end_ - begin_; } inline IdSetLexicon::IdSet::IdSet() : begin_(&singleton_id_), end_(begin_) { } inline IdSetLexicon::IdSet::IdSet(Iterator begin, Iterator end) : begin_(begin), end_(end) { } inline IdSetLexicon::IdSet::IdSet(int32_t singleton_id) : begin_(&singleton_id_), end_(&singleton_id_ + 1), singleton_id_(singleton_id) {} inline int32_t IdSetLexicon::AddSingleton(int32_t id) const { ABSL_DCHECK_GE(id, 0); ABSL_DCHECK_LE(id, std::numeric_limits::max()); // Singleton sets are represented by their element. return id; } /*static*/ inline int32_t IdSetLexicon::EmptySetId() { return kEmptySetId; } template int32_t IdSetLexicon::Add(FwdIterator begin, FwdIterator end) { tmp_.clear(); for (; begin != end; ++begin) { ABSL_DCHECK_GE(*begin, 0); ABSL_DCHECK_LE(*begin, std::numeric_limits::max()); tmp_.push_back(*begin); } return AddInternal(&tmp_); } template int32_t IdSetLexicon::Add(const Container& container) { return Add(std::begin(container), std::end(container)); } #endif // S2_ID_SET_LEXICON_H_ src/s2/id_set_lexicon_test.cc000066400000000000000000000043241524103652300165330ustar00rootroot00000000000000// Copyright 2016 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/id_set_lexicon.h" #include #include #include #include #include #include #include "absl/types/span.h" using std::vector; void ExpectIdSet(absl::Span expected, const IdSetLexicon::IdSet& actual) { EXPECT_EQ(expected.size(), actual.size()); EXPECT_TRUE(std::equal(expected.begin(), expected.end(), actual.begin())); } using IdSet = IdSetLexicon::IdSet; using Seq = vector; TEST(IdSetLexicon, EmptySet) { IdSetLexicon lexicon; ExpectIdSet({}, lexicon.id_set(lexicon.Add(Seq{}))); } TEST(IdSetLexicon, SingletonSets) { IdSetLexicon lexicon; EXPECT_EQ(5, lexicon.Add(Seq{5})); EXPECT_EQ(0, lexicon.Add(Seq{0, 0})); EXPECT_EQ(1, lexicon.AddSingleton(1)); int32_t m = std::numeric_limits::max(); EXPECT_EQ(m, lexicon.Add(&m, &m + 1)); ExpectIdSet({0}, lexicon.id_set(0)); ExpectIdSet({1}, lexicon.id_set(1)); ExpectIdSet({5}, lexicon.id_set(5)); ExpectIdSet({m}, lexicon.id_set(m)); } TEST(IdSetLexicon, SetsAreSorted) { IdSetLexicon lexicon; EXPECT_EQ(~0, lexicon.Add(Seq{2, 5})); EXPECT_EQ(~1, lexicon.Add(Seq{3, 2, 5})); EXPECT_EQ(~0, lexicon.Add(Seq{5, 2})); EXPECT_EQ(~1, lexicon.Add(Seq{5, 3, 2, 5})); ExpectIdSet({2, 5}, lexicon.id_set(~0)); ExpectIdSet({2, 3, 5}, lexicon.id_set(~1)); } TEST(IdSetLexicon, Clear) { IdSetLexicon lexicon; EXPECT_EQ(~0, lexicon.Add(Seq{1, 2})); EXPECT_EQ(~1, lexicon.Add(Seq{3, 4})); lexicon.Clear(); EXPECT_EQ(~0, lexicon.Add(Seq{3, 4})); EXPECT_EQ(~1, lexicon.Add(Seq{1, 2})); } src/s2/internal/000077500000000000000000000000001524103652300140065ustar00rootroot00000000000000src/s2/internal/s2disjoint_set.h000066400000000000000000000113351524103652300171250ustar00rootroot00000000000000// Copyright 2022 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: smcallis@google.com (Sean McAllister) #ifndef S2_INTERNAL_S2DISJOINT_SET_H_ #define S2_INTERNAL_S2DISJOINT_SET_H_ #include #include "absl/container/flat_hash_map.h" #include "absl/log/absl_check.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep namespace internal { // A disjoint set (AKA union-find set, AKA merge-find set) is a data structure // that stores a partition of a set into disjoint subsets. It allows us to // efficiently add, merge and find a representative member of a set. // // In practice, disjoint sets are used for connected-component like algorithms // where we want to build up relationships between subsets and query the final // connected pieces. // // This implementation uses both path compression and union-by-size, so both the // Union and FindRoot operations have O(a(N)) amortized complexity, where a(n) // is the inverse Ackermann function. For any value that we'll ever care about, // a(n) is less than 5, which is, for all practical purposes, constant. template class DisjointSet { public: // Adds a new element to the set. The root of the element is itself, that is, // it's disjoint from all the other elements of the set. // // If the element is already in the set, no changes are made and false is // returned, otherwise true. // // Immediately after calling Add(val), FindRoot(val) == val. bool Add(const T& val); // Finds the root of the given element. If the element isn't in the set, // the returned optional has no value, otherwise it will contain the root. std::optional FindRoot(const T& val); // Performs union of two subsets. Makes the parent of a's subset equal to the // parent of b's subset. If either a or b isn't in the set, returns false and // does not modify the set. bool Union(const T& a, const T& b); // Returns the total number of elements in the set. int Size() const { return nodes_.size(); } // Clears the set so that Size() == 0. void Clear() { nodes_.clear(); } // Reserve space for at least num elements. void Reserve(int num) { nodes_.reserve(num); } private: struct Node { explicit Node(const T& value) : value(value) {} T value; int size = 1; }; // Implementation for find root, expects that val is in the set. Recursively // seeks to the root of the set and sets each element's parent to the root as // it goes, returning a reference to the root node. Node& FindRootImpl(const T& val); absl::flat_hash_map nodes_; }; template bool DisjointSet::Add(const T& val) { return nodes_.emplace(val, Node(val)).second; } template std::optional DisjointSet::FindRoot(const T& val) { // Val might not be in the table at all, so use find for first lookup. auto iter = nodes_.find(val); if (iter == nodes_.end()) { return {}; } Node& node = iter->second; if (node.value == val) { return val; } return node.value = FindRootImpl(node.value).value; } template typename DisjointSet::Node& DisjointSet::FindRootImpl(const T& val) { auto iter = nodes_.find(val); ABSL_DCHECK(iter != nodes_.end()); Node& node = iter->second; if (node.value == val) { return node; } // It can be shown that a disjoint set of size N has an upper bound on its // height of floor(log(N)). So even a billion element set will only recurse // 30 levels in the worst case here. Node& root = FindRootImpl(node.value); node.value = root.value; return root; } template bool DisjointSet::Union(const T& a, const T& b) { auto iter_a = nodes_.find(a); if (iter_a == nodes_.end()) { return false; } auto iter_b = nodes_.find(b); if (iter_b == nodes_.end()) { return false; } Node& root_a = FindRootImpl(iter_a->second.value); Node& root_b = FindRootImpl(iter_b->second.value); if (root_a.value != root_b.value) { if (root_a.size < root_b.size) { root_a.value = root_b.value; root_b.size += root_a.size; } else { root_b.value = root_a.value; root_a.size += root_b.size; } } return true; } } // namespace internal #endif // S2_INTERNAL_S2DISJOINT_SET_H_ src/s2/internal/s2disjoint_set_test.cc000066400000000000000000000063701524103652300203250ustar00rootroot00000000000000// Copyright 2022 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: smcallis@google.com (Sean McAllister) #include "s2/internal/s2disjoint_set.h" #include #include #include #include "absl/log/absl_check.h" #include "s2/s2point.h" namespace internal { namespace { TEST(DisjointSetTest, S2PointSetCompiles) { DisjointSet set; (void)set; } TEST(DisjointSetTest, InsertMoreThanOnceFails) { DisjointSet set; EXPECT_TRUE(set.Add(1)); EXPECT_FALSE(set.Add(1)); EXPECT_FALSE(set.Add(1)); } TEST(DisjointSetTest, FindRootWorks) { DisjointSet set; set.Add(1); std::optional root = set.FindRoot(1); ABSL_CHECK(root.has_value()); EXPECT_EQ(root.value(), 1); EXPECT_FALSE(set.FindRoot(2).has_value()); } TEST(DisjointSetTest, UnionWorks) { DisjointSet set; for (int i = 0; i < 10; ++i) { ABSL_CHECK(set.Add(i)); } // Union into two disjoint sets for (int i = 0; i < 4; ++i) { ABSL_CHECK(set.Union(i + 0, i + 1)); ABSL_CHECK(set.Union(i + 5, i + 6)); } // The values in the two sets should all have the same root now. for (int i = 0; i < 5; ++i) { std::optional root = set.FindRoot(i); ABSL_CHECK(root.has_value()); EXPECT_EQ(root.value(), 0); root = set.FindRoot(i + 5); ABSL_CHECK(root.has_value()); EXPECT_EQ(root.value(), 5); } // Check that attempting to union with something not in the set fails. EXPECT_FALSE(set.Union(0, 13)); EXPECT_FALSE(set.Union(13, 0)); EXPECT_FALSE(set.Union(12, 13)); // Union of two elements from two sets should unify the sets ABSL_CHECK(set.Union(3, 7)); for (int i = 0; i < 10; ++i) { std::optional root = set.FindRoot(i); ABSL_CHECK(root.has_value()); EXPECT_EQ(root.value(), 0); } } TEST(DisjointSetTest, SizeAndClearWorks) { DisjointSet set; set.Reserve(10); for (int i = 0; i < 10; ++i) { ABSL_CHECK(set.Add(i)); } EXPECT_EQ(set.Size(), 10); for (int i = 0; i < set.Size() - 1; ++i) { ABSL_CHECK(set.Union(i, i + 1)); } // Unioning doesn't change size. EXPECT_EQ(set.Size(), 10); set.Clear(); EXPECT_EQ(set.Size(), 0); } void BM_FindRoot(benchmark::State &state) { int size = state.range(0); DisjointSet set; set.Reserve(size); for (int i = 0; i < size; ++i) { set.Add(i); } // Union consecutive sets together to form a chain that can be length N. for (int i = 0; i < set.Size() - 1; ++i) { set.Union(i, i + 1); } // Benchmark the FindRoot time. for (auto _ : state) { benchmark::DoNotOptimize(set.FindRoot(1)); } state.SetItemsProcessed(state.iterations()); } BENCHMARK(BM_FindRoot)->Range(2, 1 << 20); } // namespace } // namespace internal src/s2/internal/s2incident_edge_tracker.cc000066400000000000000000000057611524103652300210670ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/internal/s2incident_edge_tracker.h" #include #include #include "absl/log/absl_check.h" namespace internal { void S2IncidentEdgeTracker::StartShape(int shape_id) { nursery_.clear(); current_shape_ = shape_id; } void S2IncidentEdgeTracker::AddEdge(int edge_id, const S2Shape::Edge& edge) { ABSL_DCHECK_GE(current_shape_, 0); // Push non-degenerate edges into the nursery. nursery_.push_back({edge.v0, edge_id}); if (!edge.IsDegenerate()) { nursery_.push_back({edge.v1, edge_id}); } } void S2IncidentEdgeTracker::FinishShape() { ABSL_DCHECK_GE(current_shape_, 0); using std::swap; // We want to keep any vertices with more than two incident edges. We could // sort the array by vertex and remove any with fewer, but that would require // shifting the array and could turn quadratic quickly. // // Instead we'll scan forward from each vertex, swapping entries with the same // vertex into a contiguous range. Once we've done all the swapping we can // just make sure that we have at least three edges in the range. const int nursery_size = nursery_.size(); for (int start = 0; start < nursery_size;) { int end = start + 1; // Scan to the end of the array, swap entries so that entries with the same // vertex as the start are adjacent. int next = start; const S2Point& curr_vertex = nursery_[start].vertex; while (++next < nursery_size) { if (nursery_[next].vertex == curr_vertex) { swap(nursery_[next], nursery_[end++]); } } // Most vertices will have two incident edges (the incoming edge and the // outgoing edge), which aren't interesting, skip them. const int num_edges = end - start; if (ABSL_PREDICT_TRUE(num_edges <= 2)) { start = end; continue; } const IncidentEdgeKey key = {current_shape_, nursery_[start].vertex}; // If we don't have this key yet, create it manually with a pre-sized // hash set to avoid rehashes. Start with a size of 8, which is four // edges with a load factor of 50%. auto iter = incident_edge_map_.find(key); if (iter == incident_edge_map_.end()) { iter = incident_edge_map_.emplace(key, 8).first; } absl::flat_hash_set& edges = iter->second; edges.reserve(edges.size() + num_edges); while (start != end) { edges.insert({nursery_[start++].edge_id}); } } } } // namespace internal src/s2/internal/s2incident_edge_tracker.h000066400000000000000000000125201524103652300207200ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_INTERNAL_S2INCIDENT_EDGE_TRACKER_H_ #define S2_INTERNAL_S2INCIDENT_EDGE_TRACKER_H_ #include #include #include #include #include "absl/container/btree_map.h" #include "absl/container/flat_hash_set.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s2point.h" #include "s2/s2shape.h" namespace internal { // A tuple of (shape id, vertex) that compares by shape id. struct IncidentEdgeKey { IncidentEdgeKey() = default; explicit IncidentEdgeKey(int shape_id) : shape_id(shape_id) { /* Leave vertex undefined */ } IncidentEdgeKey(int shape_id, S2Point vertex) : shape_id(shape_id), vertex(vertex) {} int32_t shape_id; S2Point vertex; // We need a strict ordering to be a valid key for an ordered container, but // we don't actually care about the ordering of the vertices (as long as // they're grouped by shape id). Vertices are 3D points so they don't have a // natural ordering, so we'll just compare them lexicographically. bool operator<(const IncidentEdgeKey& b) const { if (shape_id < b.shape_id) return true; if (shape_id > b.shape_id) return false; for (int i = 0; i < 3; ++i) { if (vertex[i] < b.vertex[i]) return true; if (vertex[i] > b.vertex[i]) return false; } return false; // Must be equal. } }; // Map from keys of (shape id, vertex) to a set of edge_ids. We can and do // encounter the same edges multiple times, so we need to use a set to // deduplicate edges as they're inserted. using IncidentEdgeSet = absl::btree_map>; // A class for detecting and tracking shape edges that are incident on the same // vertex. Edges of multiple shapes may be tracked, but lookup is by shape id // and vertex: there is no facility to get all edges of all shapes at a vertex. // Edge vertices must compare exactly equal to be considered the same vertex, no // tolerance is applied as this isn't intended for e.g.: snapping shapes // together, which S2Builder does better and more robustly. // // To use, instantiate and then add edges with one or more sequences of calls, // where each sequence begins with StartShape(), followed by AddEdge() calls to // add edges for that shape, and ends with FinishShape(). Those sequences do // not need to visit shapes or edges in order. Then, call incidentEdges() to get // the resulting map from IncidentEdgeKeys (which are shapeId, vertex pairs) to // a set of edgeIds of the shape that are incident to that vertex.. // // This works on a block of edges at a time, meaning that to detect incident // edges on a particular vertex, we must have at least three edges incident // at that vertex when FinishShape() is called. We don't maintain partial // information between calls. However, subject to this constraint, a single // shape's edges may be defined with multiple sequences of StartShape(), // AddEdge()... , FinishShape() calls. // // The reason for this is simple: most edges don't have more than two incident // edges (the incoming and outgoing edge). If we had to maintain information // between calls, we'd end up with a map that contains every vertex, to no // benefit. Instead, when FinishShape() is called, we discard vertices that // contain two or fewer incident edges. // // In principle this isn't a real limitation because generally we process an // S2ShapeIndex cell at a time, and, if a vertex has multiple edges, we'll see // all the edges in the same cell as the vertex, and, in general, it's possible // to aggregate edges before calling. // // The tracker maintains incident edges until it's cleared. If you call it with // each cell from an S2ShapeIndex, then at the end you will have all the // incident edge information for the whole index. If only a subset is needed, // call Reset() when you're done. class S2IncidentEdgeTracker { public: // Add edges to the edge tracker. After calling, any vertices with multiple // (> 2) incident edges will appear in the incident edge map. void StartShape(int shape_id); void AddEdge(int edge_id, const S2Shape::Edge& edge); void FinishShape(); // Clear any accumulated state. void Reset() { incident_edge_map_.clear(); } // Returns a const reference to the incident edge map. const IncidentEdgeSet& IncidentEdges() const { return incident_edge_map_; } private: // Scratch space to temporarily store incident edges in. Having a separate // space for these lets us remove vertices with only one incident edge // easily. struct VertexEdge { S2Point vertex; int32_t edge_id; }; std::vector nursery_; int current_shape_ = -1; // Actual incident edge map. IncidentEdgeSet incident_edge_map_; }; } // namespace internal #endif // S2_INTERNAL_S2INCIDENT_EDGE_TRACKER_H_ src/s2/internal/s2index_cell_data.cc000066400000000000000000000146231524103652300176670ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/internal/s2index_cell_data.h" #include #include #include #include "absl/log/absl_check.h" #include "s2/mutable_s2shape_index.h" #include "s2/s2cell.h" #include "s2/s2padded_cell.h" #include "s2/s2shape.h" namespace internal { void S2IndexCellData::LoadCell(const S2ShapeIndex* index, S2CellId id, const S2ShapeIndexCell* cell) { ABSL_DCHECK_NE(index, nullptr); if (index_ == index && cell_id_ == id) { return; } index_ = index; // Cache cell information. cell_ = cell; cell_id_ = id; // Reset atomic flags so we'll recompute cached values. These form a write // barrier with the write to cell_id_ above and so should stay below it. s2cell_set_.store(false, std::memory_order_release); center_set_.store(false, std::memory_order_release); // Clear previous edges. Reserve one slot in case we don't decode _any_ edges // (e.g. an interior cell or all the dimensions are unwanted, so we don't // try to create spans with a nullptr). edges_.clear(); shape_regions_.clear(); // Reset per-dimension region information. for (auto& region : dim_regions_) { region = Region(); } int min_dim = 0; while (min_dim <= 2 && !dim_wanted(min_dim)) { ++min_dim; } int max_dim = 2; while (max_dim >= 0 && !dim_wanted(max_dim)) { --max_dim; } // No dimensions wanted, we're done. if (min_dim > 2 || max_dim < 0) { return; } for (int dim = min_dim; dim <= max_dim; ++dim) { int dim_start = edges_.size(); for (const S2ClippedShape& clipped : cell_->clipped_shapes()) { int shape_id = clipped.shape_id(); const S2Shape& shape = *index->shape(shape_id); // Only process the current dimension. if (shape.dimension() != dim) { continue; } // In the event we wanted dimensions 0 and 2, but not 1. if (!dim_wanted(dim)) { continue; } // Materialize clipped shape edges into the edges vector. Track where we // start so we can add information about the region for this shape. int shape_start = edges_.size(); for (int i = 0; i < clipped.num_edges(); ++i) { int edge_id = clipped.edge(i); // Looking up an edge requires looking up which chain it's in, which is // often a binary search. So let's manually lookup the chain // information and use that to find the edge, so we only have to do that // search once. S2Shape::ChainPosition position = shape.chain_position(edge_id); S2Shape::Edge edge = shape.chain_edge(position.chain_id, position.offset); edges_.emplace_back(edge, edge_id, position); } // Note which block of edges belongs to the shape. shape_regions_.emplace_back(std::make_pair( shape_id, Region{shape_start, edges_.size() - shape_start})); } // Save region information for the current dimension. dim_regions_[dim] = {dim_start, edges_.size() - dim_start}; } } absl::Span S2IndexCellData::shape_edges( int id) const { for (const auto& iter : shape_regions_) { if (iter.first == id) { Region region = iter.second; if (static_cast(region.start) < edges_.size()) { return {&edges_[region.start], region.size}; } return {}; } } return {}; } absl::Span S2IndexCellData::dim_edges( int dim) const { ABSL_DCHECK(0 <= dim && dim <= 2); const Region& region = dim_regions_[dim]; if (static_cast(region.start) < edges_.size()) { return {&edges_[region.start], region.size}; } return {}; } absl::Span S2IndexCellData::dim_range_edges(int dim0, int dim1) const { ABSL_DCHECK_LE(dim0, dim1); ABSL_DCHECK(0 <= dim0 && dim0 <= 2); ABSL_DCHECK(0 <= dim1 && dim1 <= 2); size_t start = dim_regions_[dim0].start; size_t size = 0; for (int dim = dim0; dim <= dim1; ++dim) { start = std::min(start, static_cast(dim_regions_[dim].start)); size += dim_regions_[dim].size; } if (start < edges_.size()) { return {&edges_[start], size}; } return {}; } bool S2IndexCellData::ShapeContains(const S2ClippedShape& clipped, const S2Point& point, S2VertexModel model) const { #ifndef NDEBUG R2Rect bounds = S2PaddedCell(id(), MutableS2ShapeIndex::kCellPadding).bound(); R2Point uv; S2::ValidFaceXYZtoUV(S2Cell(id()).face(), point, &uv); ABSL_DCHECK(bounds.Contains(uv)); #endif // Points and polylines don't contain anything except under the CLOSED model. const S2Shape& shape = *index_->shape(clipped.shape_id()); if (shape.dimension() < 2) { if (model != S2VertexModel::CLOSED) { return false; } // Point/polyline only contains point if it's a vertex. for (const EdgeAndIdChain& edge : shape_edges(clipped.shape_id())) { if (edge.v0 == point || edge.v1 == point) { return true; } } return false; } // Test containment by drawing a line segment from the cell center to the // given point and counting edge crossings. S2Point center = this->center(); S2EdgeCrosser crosser(¢er, &point); bool inside = clipped.contains_center(); for (const EdgeAndIdChain& edge : shape_edges(clipped.shape_id())) { int sign = crosser.CrossingSign(&edge.v0, &edge.v1); if (sign < 0) continue; if (sign == 0) { // For the OPEN and CLOSED models, check whether point is a vertex. if (model != S2VertexModel::SEMI_OPEN && (edge.v0 == point || edge.v1 == point)) { return (model == S2VertexModel::CLOSED); } sign = S2::VertexCrossing(*crosser.a(), *crosser.b(), edge.v0, edge.v1); } inside ^= sign; } return inside; } } // namespace internal src/s2/internal/s2index_cell_data.h000066400000000000000000000246161524103652300175340ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_INTERNAL_S2INDEX_CELL_DATA_H_ #define S2_INTERNAL_S2INDEX_CELL_DATA_H_ #include #include #include #include #include #include "absl/base/thread_annotations.h" #include "absl/log/absl_check.h" #include "absl/synchronization/mutex.h" #include "absl/types/span.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s2cell.h" #include "s2/s2cell_id.h" #include "s2/s2contains_point_query.h" #include "s2/s2point.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" // A class for working with S2ShapeIndexCell data. For larger queries like // validation, we often look up edges multiple times, and sometimes need to // work with the edges themselves, their edge ids, or their chain and offset. // // S2ShapeIndexCell and the S2ClippedShape APIs fundamentally work with edge ids // and can't be re-worked without significant effort and loss of efficiency. // This class provides an alternative API than repeatedly querying through the // shapes in the index. // // This is meant to support larger querying and validation operations such as // S2ValidationQuery that have to proceed cell-by cell through an index. // // To use, simply call LoadCell() to decode the contents of a cell. // // The class promises that the edges will be looked up once when LoadCell() is // called, and the edges, edge_ids, chain, and chain offsets are loaded into a // contiguous chunk of memory that we can serve requests from via absl::Span. // Since the chain and offset are computed anyways when looking up an edge via // the shape.edge() API, we simply cache those values so the cost is minimal. // // The memory layout looks like this: // // | 0D Shapes | 1D Shapes | 2D Shapes | Dimensions // | 5 | 1 | 3 | 2 | 7 | 0 | 6 | 4 | 8 | Shapes // [ ......................... Edges ..........................] Edges // // This allows us to look up individual shapes very quickly, as well as all // shapes in a given dimension or contiguous range of dimensions: // // Edges() - Return Span over all edges. // ShapeEdges() - Return Span over edges of a given shape. // DimEdges() - Return Span over all edges of a given dimension. // DimRangeEges() - Return Span over all edges of a range of dimensions. // // We use a stable sort, so similarly to S2ShapeIndexCell, we promise that // shapes _within a dimension_ are in the same order they are in the index // itself, and the edges _within a shape_ are similarly in the same order. // // The clipped shapes in a cell are exposed through the Shapes() method. // namespace internal { class S2IndexCellData { public: // Extension of Edge with fields for the edge id, chain id, and offset. It's // useful to bundle these together when decoding S2ShapeIndex cells because it // allows us to avoid repetitive edge and chain lookups in many cases. struct EdgeAndIdChain : S2Shape::Edge { EdgeAndIdChain() = default; EdgeAndIdChain(const Edge& edge, int edge_id, int chain, int offset) : Edge(edge), id(edge_id), chain(chain), offset(offset) {} EdgeAndIdChain(const Edge& edge, int edge_id, S2Shape::ChainPosition pos) : Edge(edge), id(edge_id), chain(pos.chain_id), offset(pos.offset) {} friend bool operator==(const EdgeAndIdChain& x, const EdgeAndIdChain& y) { return x.v0 == y.v0 && x.v1 == y.v1; } friend bool operator<(const EdgeAndIdChain& x, const EdgeAndIdChain& y) { return x.v0 < y.v0 || (x.v0 == y.v0 && x.v1 < y.v1); } int32_t id; // Id of the edge within its shape. int32_t chain; // Id of the chain the edge belongs to. int32_t offset; // Offset of the edge within the chain. }; S2IndexCellData() = default; S2IndexCellData(const S2ShapeIndex* index, S2CellId id, const S2ShapeIndexCell* cell) { LoadCell(index, id, cell); } // Resets internal state to defaults without de-allocating memory. The next // call to LoadCell() will process the cell regardless of whether it was // already loaded. Should be called when processing a new index. void Reset() { index_ = nullptr; cell_ = nullptr; edges_.clear(); shape_regions_.clear(); dim_wanted_[0] = dim_wanted_[1] = dim_wanted_[2] = true; } // Returns true if a dimension (0, 1, or 2) is set to be decoded. bool dim_wanted(int dim) const { ABSL_DCHECK(0 <= dim && dim <= 2); return dim_wanted_[dim]; } // Configures whether a particular dimension of shape should be decoded. void set_dim_wanted(int dim, bool wanted) { ABSL_DCHECK(0 <= dim && dim <= 2); dim_wanted_[dim] = wanted; } // Returns the id of the current cell. S2CellId id() const { return cell_id_; } // Returns a const pointer to the index of the current cell. const S2ShapeIndex* index() const { return index_; } // Returns an S2Cell instance for the current cell. const S2Cell& cell() const { if (!s2cell_set_.load(std::memory_order_acquire)) { absl::MutexLock lock(lock_); if (!s2cell_set_.load(std::memory_order_relaxed)) { s2cell_ = S2Cell(cell_id_); s2cell_set_.store(true, std::memory_order_release); } } // `s2cell_` is set once an for all, it won't change after this function // returns. return ABSL_TS_UNCHECKED_READ(s2cell_); } // Returns the center point of the current cell. const S2Point& center() const { if (!center_set_.load(std::memory_order_acquire)) { absl::MutexLock lock(lock_); if (!center_set_.load(std::memory_order_relaxed)) { cell_center_ = cell_id_.ToPoint(); center_set_.store(true, std::memory_order_release); } } // `cell_center_` is set once an for all, it won't change after this // function returns. return ABSL_TS_UNCHECKED_READ(cell_center_); } // Loads the data from the given cell, previous cell data is cleared. Both // the index and cell lifetimes must span the lifetime until the class is // destroyed or LoadCell() is called again, so we take by const pointer to // avoid binding temporaries. // // If the index, id and cell pointer are the same as in the previous call to // LoadCell, loading is not performed since we already have the data decoded. void LoadCell(const S2ShapeIndex* index, S2CellId id, const S2ShapeIndexCell* cell); // Returns the number of clipped shapes in the cell. int num_clipped() const { return cell_->num_clipped(); } // Returns a reference to the S2Shape for the given clipped shape. The // returned reference is to a shape owned by the index passed to LoadCell(). const S2Shape& shape(const S2ClippedShape& clipped) const { const S2Shape* shape = index_->shape(clipped.shape_id()); ABSL_DCHECK_NE(shape, nullptr); return *shape; } // Same as above but takes the shape id directly. const S2Shape& shape(int shape_id) const { const S2Shape* shape = index_->shape(shape_id); ABSL_DCHECK_NE(shape, nullptr); return *shape; } // Return a constant view over the clipped shapes in the cell. absl::Span clipped_shapes() const { return cell_->clipped_shapes(); } // Returns a view into all the edges in the current cell. absl::Span edges() const { return edges_; } // Returns a view into the edges in the current cell for a given shape. // REQUIRES: id is an id for one of the shapes in Shapes() absl::Span shape_edges(int shape_id) const; // Returns a view into the edges in the current cell for a given dimension. // REQUIRES: dim is a valid dimension (0, 1, or 2) absl::Span dim_edges(int dim) const; // Returns a view into the edges in the current cell for a range of // dimensions. // REQUIRES: dimensions are valid (0, 1, or 2) absl::Span dim_range_edges(int dim0, int dim1) const; // Tests whether a shape in the current cell contains a point. The logic here // is is the same as S2ContainsPointQuery::ShapeContains but only applies to // the current cell and doesn't have to lookup edges or cell centers again. // // Since this _only_ operates on edges within the current cell, it must not // be used to test points that are outside of the current cell, as there may // be intervening edges between the point and the cell center that we can't // see. // // By default operates with an OPEN vertex model. // // REQUIRES: The cell must contain point. bool ShapeContains(const S2ClippedShape& clipped, const S2Point& point, S2VertexModel model = S2VertexModel::OPEN) const; private: const S2ShapeIndex* index_ = nullptr; const S2ShapeIndexCell* cell_ = nullptr; S2CellId cell_id_; // Computing the cell center and S2Cell can cost as much as looking up the // edges themselves, so defer doing it until needed. We want to be able to // access the values through a const reference though, so we have to // synchronize access ourselves. // // TODO(b/335677213): Use std::atomic_flag instead when C++20 is allowed. mutable std::atomic s2cell_set_ = false; mutable std::atomic center_set_ = false; mutable absl::Mutex lock_; mutable S2Cell s2cell_ ABSL_GUARDED_BY(lock_); mutable S2Point cell_center_ ABSL_GUARDED_BY(lock_); // Dimensions that we wish to decode, the default is all of them. bool dim_wanted_[3] = {true, true, true}; // Storage space for edges of the current cell. std::vector edges_; // Simple pair for defining an integer valued region. struct Region { int start = 0; size_t size = 0; }; // Map from shape id to the region of the edges_ array it's stored in. std::vector> shape_regions_; // Region for each dimension we might encounter. Region dim_regions_[3]; }; } // namespace internal #endif // S2_INTERNAL_S2INDEX_CELL_DATA_H_ src/s2/internal/s2index_cell_data_test.cc000066400000000000000000000125731524103652300207300ustar00rootroot00000000000000// Copyright 2022 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: smcallis@google.com (Sean McAllister) #include "s2/internal/s2index_cell_data.h" #include #include #include #include "absl/log/absl_check.h" #include "s2/mutable_s2shape_index.h" #include "s2/s2cell_range_iterator.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" namespace internal { namespace { using ::std::unique_ptr; using ::testing::Eq; using ::testing::IsEmpty; using ::testing::Ne; using ::testing::Not; using ::testing::NotNull; TEST(S2IndexCellData, Accessors) { // Provide some test coverage for accessors so they are not detected as // dead code. unique_ptr index = s2textformat::MakeIndexOrDie("0:0 ##"); MutableS2ShapeIndex::Iterator iter(index.get(), S2ShapeIndex::BEGIN); S2IndexCellData data; data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.index(), NotNull()); EXPECT_THAT(data.num_clipped(), Eq(1)); } TEST(S2IndexCellData, DimensionFilteringWorks) { unique_ptr index = s2textformat::MakeIndexOrDie( "0:0" "#1:1, 2:2" "#1:0, 0:1, -1:0, 0:-1"); MutableS2ShapeIndex::Iterator iter(index.get(), S2ShapeIndex::BEGIN); { // Check that we get all dimensions by default. S2IndexCellData data; data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_edges(0), Not(IsEmpty())); EXPECT_THAT(data.dim_edges(1), Not(IsEmpty())); EXPECT_THAT(data.dim_edges(2), Not(IsEmpty())); } { // No dimensions should work too, we just don't decode edges. S2IndexCellData data; data.set_dim_wanted(0, false); data.set_dim_wanted(1, false); data.set_dim_wanted(2, false); data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_edges(0), IsEmpty()); EXPECT_THAT(data.dim_edges(1), IsEmpty()); EXPECT_THAT(data.dim_edges(2), IsEmpty()); } // Should be able to get ranges even if a dimension is turned off. { S2IndexCellData data; data.set_dim_wanted(0, false); data.set_dim_wanted(1, true); data.set_dim_wanted(2, true); data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_range_edges(0, 0), IsEmpty()); EXPECT_THAT(data.dim_range_edges(0, 2), Not(IsEmpty())); } { S2IndexCellData data; data.set_dim_wanted(0, false); data.set_dim_wanted(1, true); data.set_dim_wanted(2, false); data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_edges(0), IsEmpty()); EXPECT_THAT(data.dim_edges(1), Not(IsEmpty())); EXPECT_THAT(data.dim_edges(2), IsEmpty()); } { S2IndexCellData data; data.set_dim_wanted(0, true); data.set_dim_wanted(1, false); data.set_dim_wanted(2, true); data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_edges(0), Not(IsEmpty())); EXPECT_THAT(data.dim_edges(1), IsEmpty()); EXPECT_THAT(data.dim_edges(2), Not(IsEmpty())); } { S2IndexCellData data; data.set_dim_wanted(0, true); data.set_dim_wanted(1, false); data.set_dim_wanted(2, false); data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_edges(0), Not(IsEmpty())); EXPECT_THAT(data.dim_edges(1), IsEmpty()); EXPECT_THAT(data.dim_edges(2), IsEmpty()); } { S2IndexCellData data; data.set_dim_wanted(0, false); data.set_dim_wanted(1, false); data.set_dim_wanted(2, true); data.LoadCell(index.get(), iter.id(), &iter.cell()); EXPECT_THAT(data.dim_edges(0), IsEmpty()); EXPECT_THAT(data.dim_edges(1), IsEmpty()); EXPECT_THAT(data.dim_edges(2), Not(IsEmpty())); } } // We cache cell centers and S2Cell instances because they're expensive to // compute if they're not needed. Make sure that when we load a new unique // cell, those values are updated if we access them. TEST(S2IndexCellData, CellAndCenterRecomputed) { // A line between two faces will guarantee we get at least two cells. unique_ptr index = s2textformat::MakeIndexOrDie("# 0:0, 0:-90 #"); S2IndexCellData data; auto iter = MakeS2CellRangeIterator(index.get()); data.LoadCell(index.get(), iter.id(), &iter.iterator().cell()); const S2Point center0 = data.center(); const S2Cell cell0 = data.cell(); iter.Next(); ABSL_CHECK(!iter.done()); data.LoadCell(index.get(), iter.id(), &iter.iterator().cell()); const S2Point center1 = data.center(); const S2Cell cell1 = data.cell(); EXPECT_THAT(cell0, Ne(cell1)); EXPECT_THAT(center0, Ne(center1)); // Load the same cell again, nothing should change. data.LoadCell(index.get(), iter.id(), &iter.iterator().cell()); const S2Point center2 = data.center(); const S2Cell cell2 = data.cell(); EXPECT_THAT(cell1, Eq(cell2)); EXPECT_THAT(center1, Eq(center2)); } } // namespace } // namespace internal src/s2/internal/s2meta.h000066400000000000000000000033021524103652300153500ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_INTERNAL_S2META_H_ #define S2_INTERNAL_S2META_H_ #include #include "absl/meta/type_traits.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep // This file contains functions for meta programming, primarily related to // checking that the type of an opaque template parameter is an instance of some // S2 base type. These are defined internally to avoid clients relying on them. // A variable template to check if a type is derived from another type ignoring // cv and reference qualifiers. This is similar to std::derived_from which was // added in C++20. // // TODO(b/335677213): Remove this when we have access to C++20. namespace s2meta { template using derived_from = absl::conjunction< std::is_base_of, std::decay_t>, std::is_convertible*, const volatile std::decay_t*>>; template constexpr bool derived_from_v = derived_from::value; } // namespace s2meta #endif // S2_INTERNAL_S2META_H_ src/s2/mutable_s2shape_index.cc000066400000000000000000002670221524103652300167570ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/mutable_s2shape_index.h" #include #include #include #include #include #include #include #include #include "absl/base/attributes.h" #include "absl/container/btree_map.h" #include "absl/flags/flag.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/synchronization/mutex.h" #include "absl/types/span.h" #include "s2/util/coding/coder.h" #include "s2/util/coding/varint.h" #include "s2/encoded_s2cell_id_vector.h" #include "s2/encoded_string_vector.h" #include "s2/r1interval.h" #include "s2/r2.h" #include "s2/r2rect.h" #include "s2/s2cell_id.h" #include "s2/s2cell_iterator.h" #include "s2/s2cell_union.h" #include "s2/s2coords.h" #include "s2/s2edge_clipping.h" #include "s2/s2edge_crosser.h" #include "s2/s2edge_vector_shape.h" #include "s2/s2memory_tracker.h" #include "s2/s2metrics.h" #include "s2/s2padded_cell.h" #include "s2/s2point.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2shapeutil_contains_brute_force.h" #include "s2/s2shapeutil_shape_edge_id.h" #include "s2/util/gtl/compact_array.h" using std::fabs; using std::make_pair; using std::make_unique; using std::max; using std::min; using std::unique_ptr; using std::vector; // FLAGS_s2shape_index_default_max_edges_per_cell // // The default maximum number of edges per cell (not counting 'long' edges). // If a cell has more than this many edges, and it is not a leaf cell, then it // is subdivided. This flag can be overridden via MutableS2ShapeIndex::Options. // Reasonable values range from 10 to about 50 or so. ABSL_FLAG( int32_t, s2shape_index_default_max_edges_per_cell, 10, "Default maximum number of edges per cell (not counting 'long' edges); " "reasonable values range from 10 to 50. Small values makes queries " "faster, while large values make construction faster and use less memory."); // FLAGS_s2shape_index_tmp_memory_budget // // Attempt to limit the amount of temporary memory allocated while building or // updating a MutableS2ShapeIndex to at most this value. This is achieved by // splitting the updates into multiple batches when necessary. (The memory // required is proportional to the number of edges being updated at once.) // // Note that this limit is not a hard guarantee, for several reasons: // (1) the memory estimates are only approximations; // (2) all edges in a given shape are added or removed at once, so shapes // with huge numbers of edges may exceed the budget; // (3) shapes being removed are always processed in a single batch. (This // could be fixed, but it seems better to keep the code simpler for now.) ABSL_FLAG( int64_t, s2shape_index_tmp_memory_budget, int64_t{100} << 20 /*100 MB*/, "Attempts to limit the amount of temporary memory used by " "MutableS2ShapeIndex when creating or updating very large indexes to at " "most this number of bytes. If more memory than this is needed, updates " "will automatically be split into batches internally."); // FLAGS_s2shape_index_cell_size_to_long_edge_ratio // // The maximum cell size, relative to an edge's length, for which that edge is // considered 'long'. Cell size is defined as the average edge length of all // cells at a given level. For example, a value of 2.0 means that an edge E // is long at cell level k iff the average edge length at level k is at most // twice the length of E. Long edges edges are not counted towards the // max_edges_per_cell() limit because such edges typically need to be // propagated to several children, which increases time and memory costs // without commensurate benefits. ABSL_FLAG( double, s2shape_index_cell_size_to_long_edge_ratio, 1.0, "The maximum cell size, relative to an edge's length, for which that " "edge is considered 'long'. Long edges are not counted towards the " "max_edges_per_cell() limit. The size and speed of the index are " "typically not very sensitive to this parameter. Reasonable values range " "from 0.1 to 10, with smaller values causing more aggressive subdivision " "of long edges grouped closely together."); // FLAGS_s2shape_index_min_short_edge_fraction // // The minimum fraction of 'short' edges that must be present in a cell in // order for it to be subdivided. If this parameter is non-zero then the // total index size and construction time are guaranteed to be linear in the // number of input edges; this prevents the worst-case quadratic space and // time usage that can otherwise occur with certain input configurations. // Specifically, the maximum index size is // // O((c1 + c2 * (1 - f) / f) * n) // // where n is the number of input edges, f is this parameter value, and // constant c2 is roughly 20 times larger than constant c1. (The exact values // of c1 and c2 depend on the cell_size_to_long_edge_ratio and // max_edges_per_cell parameters and certain properties of the input geometry // such as whether it consists of O(1) shapes, whether it includes polygons, // and whether the polygon interiors are disjoint.) // // Reasonable parameter values range from 0.1 up to perhaps 0.95. The main // factors to consider when choosing this parameter are: // // - For pathological geometry, larger values result in indexes that are // smaller and faster to construct but have worse query performance (due to // having more edges per cell). However note that even a setting of 0.1 // reduces the worst case by 100x compared with a setting of 0.001. // // - For normal geometry, values up to about 0.8 result in indexes that are // virtually unchanged except for a slight increase in index construction // time (proportional to the parameter value f) for very large inputs. // With millions of edges, indexing time increases by about (15% * f), // e.g. a parameter value of 0.5 slows down indexing for very large inputs // by about 7.5%. (Indexing time for small inputs is not affected.) // // - Values larger than about 0.8 start to affect index construction even for // normal geometry, resulting in smaller indexes and faster construction // times but gradually worse query performance. // // Essentially this parameter provides control over a space-time tradeoff that // largely affects only pathological geometry. The default value of 0.2 was // chosen to make index construction as fast as possible while still // protecting against possible quadratic space usage. ABSL_FLAG( double, s2shape_index_min_short_edge_fraction, 0.2, "The minimum fraction of 'short' edges that must be present in a cell in " "order for it to be subdivided. If this parameter is non-zero then the " "total index size and construction time are guaranteed to be linear in the " "number of input edges, where the constant of proportionality has the " "form (c1 + c2 * (1 - f) / f). Reasonable values range from 0.1 to " "perhaps 0.95. Values up to about 0.8 have almost no effect on 'normal' " "geometry except for a small increase in index construction time " "(proportional to f) for very large inputs. For worst-case geometry, " "larger parameter values result in indexes that are smaller and faster " "to construct but have worse query performance (due to having more edges " "per cell). Essentially this parameter provides control over a space-time " "tradeoff that largely affects only pathological geometry."); // The total error when clipping an edge comes from two sources: // (1) Clipping the original spherical edge to a cube face (the "face edge"). // The maximum error in this step is S2::kFaceClipErrorUVCoord. // (2) Clipping the face edge to the u- or v-coordinate of a cell boundary. // The maximum error in this step is S2::kEdgeClipErrorUVCoord. // Finally, since we encounter the same errors when clipping query edges, we // double the total error so that we only need to pad edges during indexing // and not at query time. const double MutableS2ShapeIndex::kCellPadding = 2 * (S2::kFaceClipErrorUVCoord + S2::kEdgeClipErrorUVCoord); MutableS2ShapeIndex::Options::Options() : max_edges_per_cell_( absl::GetFlag(FLAGS_s2shape_index_default_max_edges_per_cell)) {} void MutableS2ShapeIndex::Options::set_max_edges_per_cell( int max_edges_per_cell) { max_edges_per_cell_ = max_edges_per_cell; } // FaceEdge and ClippedEdge store temporary edge data while the index is being // updated. FaceEdge represents an edge that has been projected onto a given // face, while ClippedEdge represents the portion of that edge that has been // clipped to a given S2Cell. // // While it would be possible to combine all the edge information into one // structure, there are two good reasons for separating it: // // - Memory usage. Separating the two classes means that we only need to // store one copy of the per-face data no matter how many times an edge is // subdivided, and it also lets us delay computing bounding boxes until // they are needed for processing each face (when the dataset spans // multiple faces). // // - Performance. UpdateEdges is significantly faster on large polygons when // the data is separated, because it often only needs to access the data in // ClippedEdge and this data is cached more successfully. struct MutableS2ShapeIndex::FaceEdge { int32_t shape_id; // The shape that this edge belongs to int32_t edge_id; // Edge id within that shape int32_t max_level; // Not desirable to subdivide this edge beyond this level bool has_interior; // Belongs to a shape of dimension 2. R2Point a, b; // The edge endpoints, clipped to a given face S2Shape::Edge edge; // The edge endpoints }; struct MutableS2ShapeIndex::ClippedEdge { const FaceEdge* face_edge; // The original unclipped edge R2Rect bound; // Bounding box for the clipped portion }; // Given a set of shapes, InteriorTracker keeps track of which shapes contain // a particular point (the "focus"). It provides an efficient way to move the // focus from one point to another and incrementally update the set of shapes // which contain it. We use this to compute which shapes contain the center // of every S2CellId in the index, by advancing the focus from one cell center // to the next. // // Initially the focus is at the start of the S2CellId space-filling curve. // We then visit all the cells that are being added to the MutableS2ShapeIndex // in increasing order of S2CellId. For each cell, we draw two edges: one // from the entry vertex to the center, and another from the center to the // exit vertex (where "entry" and "exit" refer to the points where the // space-filling curve enters and exits the cell). By counting edge crossings // we can incrementally compute which shapes contain the cell center. Note // that the same set of shapes will always contain the exit point of one cell // and the entry point of the next cell in the index, because either (a) these // two points are actually the same, or (b) the intervening cells in S2CellId // order are all empty, and therefore there are no edge crossings if we follow // this path from one cell to the other. class MutableS2ShapeIndex::InteriorTracker { public: // Constructs the InteriorTracker. You must call AddShape() for each shape // that will be tracked before calling MoveTo() or DrawTo(). InteriorTracker(); // Returns the initial focus point when the InteriorTracker is constructed // (corresponding to the start of the S2CellId space-filling curve). static S2Point Origin(); // Returns the current focus point (see above). const S2Point& focus() { return b_; } // Returns true if any shapes are being tracked. bool is_active() const { return is_active_; } // Adds a shape whose interior should be tracked. "contains_focus" indicates // whether the current focus point is inside the shape. Alternatively, if the // focus point is in the process of being moved (via MoveTo/DrawTo), you can // also specify "contains_focus" at the old focus point and call TestEdge() // for every edge of the shape that might cross the current DrawTo() line. // This updates the state to correspond to the new focus point. // // REQUIRES: shape->dimension() == 2 void AddShape(int32_t shape_id, bool contains_focus); // Moves the focus to the given point. This method should only be used when // it is known that there are no edge crossings between the old and new // focus locations; otherwise use DrawTo(). void MoveTo(const S2Point& b) { b_ = b; } // Moves the focus to the given point. After this method is called, // TestEdge() should be called with all edges that may cross the line // segment between the old and new focus locations. void DrawTo(const S2Point& b); // Indicates that the given edge of the given shape may cross the line // segment between the old and new focus locations (see DrawTo). // REQUIRES: shape->dimension() == 2 inline void TestEdge(int32_t shape_id, const S2Shape::Edge& edge); // The set of shape ids that contain the current focus. const ShapeIdSet& shape_ids() const { return shape_ids_; } // Indicates that the last argument to MoveTo() or DrawTo() was the entry // vertex of the given S2CellId, i.e. the tracker is positioned at the start // of this cell. By using this method together with at_cellid(), the caller // can avoid calling MoveTo() in cases where the exit vertex of the previous // cell is the same as the entry vertex of the current cell. void set_next_cellid(S2CellId next_cellid) { next_cellid_ = next_cellid.range_min(); } // Returns true if the focus is already at the entry vertex of the given // S2CellId (provided that the caller calls set_next_cellid() as each cell // is processed). bool at_cellid(S2CellId cellid) const { return cellid.range_min() == next_cellid_; } // Makes an internal copy of the state for shape ids below the given limit, // and then clear the state for those shapes. This is used during // incremental updates to track the state of added and removed shapes // separately. void SaveAndClearStateBefore(int32_t limit_shape_id); // Restores the state previously saved by SaveAndClearStateBefore(). This // only affects the state for shape_ids below "limit_shape_id". void RestoreStateBefore(int32_t limit_shape_id); // Indicates that only some edges of the given shape are being added, and // therefore its interior should not be processed yet. int partial_shape_id() const { return partial_shape_id_; } void set_partial_shape_id(int shape_id) { partial_shape_id_ = shape_id; } private: // Removes "shape_id" from shape_ids_ if it exists, otherwise insert it. void ToggleShape(int shape_id); // Returns a pointer to the first entry "x" where x >= shape_id. ShapeIdSet::iterator lower_bound(int32_t shape_id); bool is_active_ = false; S2Point a_, b_; S2CellId next_cellid_; S2EdgeCrosser crosser_; ShapeIdSet shape_ids_; // Shape ids saved by SaveAndClearStateBefore(). The state is never saved // recursively so we don't need to worry about maintaining a stack. ShapeIdSet saved_ids_; // As an optimization, we also save is_active_ so that RestoreStateBefore() // can deactivate the tracker again in the case where the shapes being added // and removed do not have an interior, but some existing shapes do. bool saved_is_active_; // If non-negative, indicates that only some edges of the given shape are // being added and therefore its interior should not be tracked yet. int partial_shape_id_ = -1; }; // As shapes are added, we compute which ones contain the start of the // S2CellId space-filling curve by drawing an edge from S2::Origin() to this // point and counting how many shape edges cross this edge. MutableS2ShapeIndex::InteriorTracker::InteriorTracker() : b_(Origin()), next_cellid_(S2CellId::Begin(S2CellId::kMaxLevel)) { } S2Point MutableS2ShapeIndex::InteriorTracker::Origin() { // The start of the S2CellId space-filling curve. return S2::FaceUVtoXYZ(0, -1, -1).Normalize(); } void MutableS2ShapeIndex::InteriorTracker::AddShape(int32_t shape_id, bool contains_focus) { is_active_ = true; if (contains_focus) { ToggleShape(shape_id); } } void MutableS2ShapeIndex::InteriorTracker::ToggleShape(int shape_id) { // Since shape_ids_.size() is typically *very* small (0, 1, or 2), it turns // out to be significantly faster to maintain a sorted array rather than // using an STL set or btree_set. if (shape_ids_.empty()) { shape_ids_.push_back(shape_id); } else if (shape_ids_[0] == shape_id) { shape_ids_.erase(shape_ids_.begin()); } else { ShapeIdSet::iterator pos = shape_ids_.begin(); while (*pos < shape_id) { if (++pos == shape_ids_.end()) { shape_ids_.push_back(shape_id); return; } } if (*pos == shape_id) { shape_ids_.erase(pos); } else { shape_ids_.insert(pos, shape_id); } } } void MutableS2ShapeIndex::InteriorTracker::DrawTo(const S2Point& b) { a_ = b_; b_ = b; crosser_.Init(&a_, &b_); } ABSL_ATTRIBUTE_ALWAYS_INLINE // ~1% faster inline void MutableS2ShapeIndex::InteriorTracker::TestEdge(int32_t shape_id, const S2Shape::Edge& edge) { if (crosser_.EdgeOrVertexCrossing(&edge.v0, &edge.v1)) { ToggleShape(shape_id); } } // Like std::lower_bound(shape_ids_.begin(), shape_ids_.end(), shape_id), but // implemented with linear rather than binary search because the number of // shapes being tracked is typically very small. inline MutableS2ShapeIndex::ShapeIdSet::iterator MutableS2ShapeIndex::InteriorTracker::lower_bound(int32_t shape_id) { ShapeIdSet::iterator pos = shape_ids_.begin(); while (pos != shape_ids_.end() && *pos < shape_id) { ++pos; } return pos; } void MutableS2ShapeIndex::InteriorTracker::SaveAndClearStateBefore( int32_t limit_shape_id) { ABSL_DCHECK(saved_ids_.empty()); ShapeIdSet::iterator limit = lower_bound(limit_shape_id); saved_ids_.assign(shape_ids_.begin(), limit); shape_ids_.erase(shape_ids_.begin(), limit); saved_is_active_ = is_active_; } void MutableS2ShapeIndex::InteriorTracker::RestoreStateBefore( int32_t limit_shape_id) { shape_ids_.erase(shape_ids_.begin(), lower_bound(limit_shape_id)); shape_ids_.insert(shape_ids_.begin(), saved_ids_.begin(), saved_ids_.end()); saved_ids_.clear(); is_active_ = saved_is_active_; } MutableS2ShapeIndex::MutableS2ShapeIndex() = default; MutableS2ShapeIndex::MutableS2ShapeIndex(const Options& options) { Init(options); } MutableS2ShapeIndex::MutableS2ShapeIndex(MutableS2ShapeIndex&& b) noexcept // S2ShapeIndex has no members. : shapes_(std::move(b.shapes_)), cell_map_(std::move(b.cell_map_)), options_(std::move(b.options_)), pending_additions_begin_(std::exchange(b.pending_additions_begin_, 0)), pending_removals_(std::move(b.pending_removals_)), index_status_(b.index_status_.exchange(FRESH, std::memory_order_relaxed)), mem_tracker_(std::move(b.mem_tracker_)) {} MutableS2ShapeIndex& MutableS2ShapeIndex::operator=( MutableS2ShapeIndex&& b) noexcept { // S2ShapeIndex has no members. shapes_ = std::move(b.shapes_); cell_map_.swap(b.cell_map_); options_ = std::move(b.options_); pending_additions_begin_ = std::exchange(b.pending_additions_begin_, 0); pending_removals_ = std::move(b.pending_removals_); index_status_.store( b.index_status_.exchange(FRESH, std::memory_order_relaxed), std::memory_order_relaxed); mem_tracker_ = std::move(b.mem_tracker_); return *this; } void MutableS2ShapeIndex::Init(const Options& options) { ABSL_DCHECK(shapes_.empty()); options_ = options; // Memory tracking is not affected by this method. } MutableS2ShapeIndex::~MutableS2ShapeIndex() { Clear(); } void MutableS2ShapeIndex::set_memory_tracker(S2MemoryTracker* tracker) { mem_tracker_.Tally(-mem_tracker_.client_usage_bytes()); mem_tracker_.Init(tracker); if (mem_tracker_.is_active()) mem_tracker_.Tally(SpaceUsed()); } // Called to set the index status when the index needs to be rebuilt. void MutableS2ShapeIndex::MarkIndexStale() { // The UPDATING status can only be changed in ApplyUpdatesThreadSafe(). if (index_status_.load(std::memory_order_relaxed) == UPDATING) return; // If a memory tracking error has occurred we set the index status to FRESH // in order to prevent us from attempting to rebuild it. IndexStatus status = (shapes_.empty() || !mem_tracker_.ok()) ? FRESH : STALE; index_status_.store(status, std::memory_order_relaxed); } void MutableS2ShapeIndex::Minimize() { mem_tracker_.Tally(-mem_tracker_.client_usage_bytes()); cell_map_.clear(); pending_removals_.reset(); pending_additions_begin_ = 0; MarkIndexStale(); if (mem_tracker_.is_active()) mem_tracker_.Tally(SpaceUsed()); } int MutableS2ShapeIndex::Add(unique_ptr shape) { // Additions are processed lazily by ApplyUpdates(). Note that in order to // avoid unexpected client behavior, this method continues to add shapes // even once the specified S2MemoryTracker limit has been exceeded. const int id = shapes_.size(); mem_tracker_.AddSpace(&shapes_, 1); shapes_.push_back(std::move(shape)); MarkIndexStale(); return id; } bool MutableS2ShapeIndex::MaybeCreatePendingRemovals() { if (!pending_removals_) { if (!mem_tracker_.Tally(sizeof(*pending_removals_))) { Minimize(); return false; } pending_removals_ = make_unique>(); } if (!mem_tracker_.AddSpace(pending_removals_.get(), 1)) { Minimize(); return false; } return true; } unique_ptr MutableS2ShapeIndex::Release(int shape_id) { // This class updates itself lazily, because it is much more efficient to // process additions and removals in batches. However this means that when // a shape is removed we need to make a copy of all its edges, since the // client is free to delete "shape" once this call is finished. ABSL_DCHECK(shapes_[shape_id] != nullptr); auto shape = std::move(shapes_[shape_id]); if (shape_id >= pending_additions_begin_) { // We are removing a shape that has not yet been added to the index, // so there is nothing else to do. } else { if (!MaybeCreatePendingRemovals()) return nullptr; // We need to make a copy of the shape data since the caller now owns the // original shape and may delete it. auto shape_copy = make_unique(); shape_copy->set_dimension(shape->dimension()); for (int i = 0; i < shape->num_edges(); ++i) { shape_copy->Add(shape->edge(i).v0, shape->edge(i).v1); } pending_removals_->push_back({shape_id, std::move(shape_copy)}); } MarkIndexStale(); return shape; } void MutableS2ShapeIndex::Remove(int shape_id) { ABSL_DCHECK(shapes_[shape_id] != nullptr); if (shape_id >= pending_additions_begin_) { // We are removing a shape that has not yet been added to the index, // so there is nothing else to do. shapes_[shape_id] = nullptr; } else { if (!MaybeCreatePendingRemovals()) return; // We don't need to copy the shape data since we own it. pending_removals_->push_back({shape_id, std::move(shapes_[shape_id])}); } MarkIndexStale(); } vector> MutableS2ShapeIndex::ReleaseAll() { ABSL_DCHECK(update_state_ == nullptr); vector> result; result.swap(shapes_); Minimize(); return result; } void MutableS2ShapeIndex::Clear() { ReleaseAll(); } // Apply any pending updates in a thread-safe way. void MutableS2ShapeIndex::ApplyUpdatesThreadSafe() { lock_.lock(); if (index_status_.load(std::memory_order_relaxed) == FRESH) { lock_.unlock(); } else if (index_status_.load(std::memory_order_relaxed) == UPDATING) { // Wait until the updating thread is finished. We do this by attempting // to lock a mutex that is held by the updating thread. When this mutex // is unlocked the index_status_ is guaranteed to be FRESH. ++update_state_->num_waiting; lock_.unlock(); update_state_->wait_mutex.lock(); lock_.lock(); --update_state_->num_waiting; UnlockAndSignal(); // Notify other waiting threads. } else { ABSL_DCHECK_EQ(STALE, index_status_); index_status_.store(UPDATING, std::memory_order_relaxed); // Allocate the extra state needed for thread synchronization. We keep // the spinlock held while doing this, because (1) memory allocation is // fast, so the chance of a context switch while holding the lock is low; // (2) by far the most common situation is that there is no contention, // and this saves an extra lock and unlock step; (3) even in the rare case // where there is contention, the main side effect is that some other // thread will burn a few CPU cycles rather than sleeping. update_state_ = make_unique(); // lock_.Lock wait_mutex *before* calling Unlock() to ensure that all other // threads will block on it. update_state_->wait_mutex.lock(); // Release the spinlock before doing any real work. lock_.unlock(); ApplyUpdatesInternal(); lock_.lock(); // index_status_ can be updated to FRESH only while locked *and* using // an atomic store operation, so that MaybeApplyUpdates() can check // whether the index is FRESH without acquiring the spinlock. index_status_.store(FRESH, std::memory_order_release); UnlockAndSignal(); // Notify any waiting threads. } } // Releases lock_ and wakes up any waiting threads by releasing wait_mutex. // If this was the last waiting thread, also deletes update_state_. // REQUIRES: lock_ is held. // REQUIRES: wait_mutex is held. inline void MutableS2ShapeIndex::UnlockAndSignal() { ABSL_DCHECK_EQ(FRESH, index_status_); int num_waiting = update_state_->num_waiting; lock_.unlock(); // Allow another waiting thread to proceed. Note that no new threads can // start waiting because the index_status_ is now FRESH, and the caller is // required to prevent any new mutations from occurring while these const // methods are running. // // We need to unlock wait_mutex before destroying it even if there are no // waiting threads. update_state_->wait_mutex.unlock(); if (num_waiting == 0) { update_state_.reset(); } } // This method updates the index by applying all pending additions and // removals. It does *not* update index_status_ (see ApplyUpdatesThreadSafe). void MutableS2ShapeIndex::ApplyUpdatesInternal() { // Check whether we have so many edges to process that we should process // them in multiple batches to save memory. Building the index can use up // to 20x as much memory (per edge) as the final index size. vector batches = GetUpdateBatches(); for (const BatchDescriptor& batch : batches) { if (mem_tracker_.is_active()) { ABSL_DCHECK_EQ(mem_tracker_.client_usage_bytes(), SpaceUsed()); // Invariant. } vector all_edges[6]; ReserveSpace(batch, all_edges); if (!mem_tracker_.ok()) return Minimize(); InteriorTracker tracker; if (pending_removals_) { // The first batch implicitly includes all shapes being removed. for (const auto& item : *pending_removals_) { RemoveShape(item.shape.get(), item.shape_id, all_edges, &tracker); } pending_removals_.reset(nullptr); } // A batch consists of zero or more full shapes followed by zero or one // partial shapes. The loop below handles all such cases. for (auto begin = batch.begin; begin < batch.end; ++begin.shape_id, begin.edge_id = 0) { const S2Shape* shape = this->shape(begin.shape_id); if (shape == nullptr) continue; // Already removed. int edges_end = begin.shape_id == batch.end.shape_id ? batch.end.edge_id : shape->num_edges(); AddShape(shape, begin.shape_id, begin.edge_id, edges_end, all_edges, &tracker); } for (int face = 0; face < 6; ++face) { UpdateFaceEdges(face, all_edges[face], &tracker); // Save memory by clearing vectors after we are done with them. vector().swap(all_edges[face]); } pending_additions_begin_ = batch.end.shape_id; if (batch.begin.edge_id > 0 && batch.end.edge_id == 0) { // We have just finished adding the edges of shape that was split over // multiple batches. Now we need to mark the interior of the shape, if // any, by setting contains_center() on the appropriate index cells. FinishPartialShape(tracker.partial_shape_id()); } if (mem_tracker_.is_active()) { mem_tracker_.Tally(-mem_tracker_.client_usage_bytes()); if (!mem_tracker_.Tally(SpaceUsed())) return Minimize(); } } // It is the caller's responsibility to update index_status_. } // Count the number of edges being updated, and break them into several // batches if necessary to reduce the amount of memory needed. (See the // documentation for FLAGS_s2shape_index_tmp_memory_budget.) vector MutableS2ShapeIndex::GetUpdateBatches() const { // Count the edges being removed and added. int num_edges_removed = 0; if (pending_removals_) { for (const auto& item : *pending_removals_) { num_edges_removed += item.shape->num_edges(); } } int64_t num_edges_added = 0; for (size_t id = pending_additions_begin_; id < shapes_.size(); ++id) { const S2Shape* shape = this->shape(id); if (shape) num_edges_added += shape->num_edges(); } BatchGenerator batch_gen(num_edges_removed, num_edges_added, pending_additions_begin_); for (size_t id = pending_additions_begin_; id < shapes_.size(); ++id) { const S2Shape* shape = this->shape(id); if (shape) batch_gen.AddShape(id, shape->num_edges()); } return batch_gen.Finish(); } // The following memory estimates are based on heap profiling. // The batch sizes during a given update gradually decrease as the space // occupied by the index itself grows. In order to do this, we need a // conservative lower bound on how much the index grows per edge. // // The final size of a MutableS2ShapeIndex depends mainly on how finely the // index is subdivided, as controlled by Options::max_edges_per_cell() and // --s2shape_index_default_max_edges_per_cell. For realistic values of // max_edges_per_cell() and shapes with moderate numbers of edges, it is // difficult to get much below 8 bytes per edge. *The minimum possible size // is 4 bytes per edge (to store a 32-bit edge id in an S2ClippedShape) plus // 24 bytes per shape (for the S2ClippedShape itself plus a pointer in the // shapes_ vector.) Note that this value is a lower bound; a typical final // index size is closer to 24 bytes per edge. static constexpr size_t kFinalBytesPerEdge = 8; // The temporary memory consists mainly of the FaceEdge and ClippedEdge // structures plus a ClippedEdge pointer for every level of recursive // subdivision. This can be more than 220 bytes per edge even for typical // geometry. (The pathological worst case is higher, but we don't use this to // determine the batch sizes.) static constexpr size_t kTmpBytesPerEdge = 226; // We arbitrarily limit the number of batches as a safety measure. With the // current default memory budget of 100 MB, this limit is not reached even // when building an index of 350 million edges. static constexpr int kMaxBatches = 100; MutableS2ShapeIndex::BatchGenerator::BatchGenerator(int64_t num_edges_removed, int64_t num_edges_added, int shape_id_begin) : max_batch_sizes_(GetMaxBatchSizes(num_edges_removed, num_edges_added)), batch_begin_(shape_id_begin, 0), shape_id_end_(shape_id_begin) { if (max_batch_sizes_.size() > 1) { ABSL_VLOG(1) << "Removing " << num_edges_removed << ", adding " << num_edges_added << " edges in " << max_batch_sizes_.size() << " batches"; } // Duplicate the last entry to simplify next_max_batch_size(). max_batch_sizes_.push_back(max_batch_sizes_.back()); // We process edge removals before additions, and edges are always removed // in a single batch. The reasons for this include: (1) removed edges use // quite a bit of memory (about 50 bytes each) and this space can be freed // immediately when we process them in one batch; (2) removed shapes are // expected to be small fraction of the index size in typical use cases // (e.g. incremental updates of large indexes), and (3) AbsorbIndexCell() // uses (shape(id) == nullptr) to detect when a shape is being removed, so // in order to split the removed shapes into multiple batches we would need // a different approach (e.g., temporarily adding fake entries to shapes_ // and restoring them back to nullptr as shapes are removed). Removing // individual shapes over multiple batches would be even more work. batch_size_ = num_edges_removed; } void MutableS2ShapeIndex::BatchGenerator::AddShape(int shape_id, int num_edges) { int batch_remaining = max_batch_size() - batch_size_; if (num_edges <= batch_remaining) { ExtendBatch(num_edges); } else if (num_edges <= next_max_batch_size()) { // Avoid splitting shapes across batches unnecessarily. FinishBatch(0, ShapeEdgeId(shape_id, 0)); ExtendBatch(num_edges); } else { // This shape must be split across at least two batches. We simply fill // each batch until the remaining edges will fit in two batches, and then // divide those edges such that both batches have the same amount of // remaining space relative to their maximum size. int e_begin = 0; while (batch_remaining + next_max_batch_size() < num_edges) { e_begin += batch_remaining; FinishBatch(batch_remaining, ShapeEdgeId(shape_id, e_begin)); num_edges -= batch_remaining; batch_remaining = max_batch_size(); } // Figure out how many edges to add to the current batch so that it will // have the same amount of remaining space as the next batch. int n = (num_edges + batch_remaining - next_max_batch_size()) / 2; FinishBatch(n, ShapeEdgeId(shape_id, e_begin + n)); FinishBatch(num_edges - n, ShapeEdgeId(shape_id + 1, 0)); } shape_id_end_ = shape_id + 1; } vector MutableS2ShapeIndex::BatchGenerator::Finish() { // We must generate at least one batch even when num_edges_removed == // num_edges_added == 0, because some shapes have an interior but no edges. // (Specifically, the full polygon has this property.) if (batches_.empty() || shape_id_end_ != batch_begin_.shape_id) { FinishBatch(0, ShapeEdgeId(shape_id_end_, 0)); } return std::move(batches_); } void MutableS2ShapeIndex::BatchGenerator::FinishBatch(int num_edges, ShapeEdgeId batch_end) { ExtendBatch(num_edges); batches_.push_back(BatchDescriptor{batch_begin_, batch_end, batch_size_}); batch_begin_ = batch_end; batch_index_edges_left_ -= batch_size_; while (batch_index_edges_left_ < 0) { batch_index_edges_left_ += max_batch_size(); batch_index_ += 1; } batch_size_ = 0; } // Divides "num_edges" edges into batches where each batch needs about the // same total amount of memory. (The total memory needed by a batch consists // of the temporary memory needed to process the edges in that batch plus the // final representations of the edges that have already been indexed.) It // uses the fewest number of batches (up to kMaxBatches) such that the total // memory usage does not exceed the combined final size of all the edges plus // FLAGS_s2shape_index_tmp_memory_budget. Returns a vector of sizes // indicating the desired number of edges in each batch. /* static */ vector MutableS2ShapeIndex::BatchGenerator::GetMaxBatchSizes( int64_t num_edges_removed, int64_t num_edges_added) { // Check whether we can update all the edges at once. int64_t num_edges_total = num_edges_removed + num_edges_added; const double tmp_memory_budget_bytes = absl::GetFlag(FLAGS_s2shape_index_tmp_memory_budget); if (num_edges_total * kTmpBytesPerEdge <= tmp_memory_budget_bytes) { return vector{static_cast(num_edges_total)}; } // Each batch is allowed to use up to "total_budget_bytes". The memory // usage consists of some number of edges already added by previous batches // (at kFinalBytesPerEdge each), plus some number being updated in the // current batch (at kTmpBytesPerEdge each). The available free space is // multiplied by (1 - kFinalBytesPerEdge / kTmpBytesPerEdge) after each // batch is processed as edges are converted into their final form. const double final_bytes = num_edges_added * kFinalBytesPerEdge; constexpr double kFinalBytesRatio = 1.0 * kFinalBytesPerEdge / kTmpBytesPerEdge; constexpr double kTmpSpaceMultiplier = 1 - kFinalBytesRatio; // The total memory budget is the greater of the final size plus the allowed // temporary memory, or the minimum amount of memory required to limit the // number of batches to "kMaxBatches". const double total_budget_bytes = max( final_bytes + tmp_memory_budget_bytes, final_bytes / (1 - std::pow(kTmpSpaceMultiplier, kMaxBatches - 1))); // "ideal_batch_size" is the number of edges in the current batch before // rounding to an integer. double ideal_batch_size = total_budget_bytes / kTmpBytesPerEdge; // Removed edges are always processed in the first batch, even if this might // use more memory than requested (see the BatchGenerator constructor). vector batch_sizes; int64_t num_edges_left = num_edges_added; if (num_edges_removed > ideal_batch_size) { batch_sizes.push_back(num_edges_removed); } else { num_edges_left += num_edges_removed; } while (num_edges_left > 0) { int batch_size = static_cast(ideal_batch_size + 1); batch_sizes.push_back(batch_size); num_edges_left -= batch_size; ideal_batch_size *= kTmpSpaceMultiplier; } ABSL_DCHECK_LE(batch_sizes.size(), kMaxBatches); return batch_sizes; } // Reserve an appropriate amount of space for the top-level face edges in the // current batch. This data structure uses about half of the temporary memory // needed during index construction. Furthermore, if the arrays are grown via // push_back() then up to 10% of the total run time consists of copying data // as these arrays grow, so it is worthwhile to preallocate space for them. void MutableS2ShapeIndex::ReserveSpace( const BatchDescriptor& batch, vector all_edges[6]) { // The following accounts for the temporary space needed for everything // except the FaceEdge vectors (which are allocated separately below). int64_t other_usage = batch.num_edges * (kTmpBytesPerEdge - sizeof(FaceEdge)); // If the number of edges is relatively small, then the fastest approach is // to simply reserve space on every face for the maximum possible number of // edges. (We use a different threshold for this calculation than for // deciding when to break updates into batches because the cost/benefit // ratio is different. Here the only extra expense is that we need to // sample the edges to estimate how many edges per face there are, and // therefore we generally use a lower threshold.) const size_t kMaxCheapBytes = min(absl::GetFlag(FLAGS_s2shape_index_tmp_memory_budget) / 2, int64_t{30} << 20 /*30 MB*/); int64_t face_edge_usage = batch.num_edges * (6 * sizeof(FaceEdge)); if (static_cast(face_edge_usage) <= kMaxCheapBytes) { if (!mem_tracker_.TallyTemp(face_edge_usage + other_usage)) { return; } for (int face = 0; face < 6; ++face) { all_edges[face].reserve(batch.num_edges); } return; } // Otherwise we estimate the number of edges on each face by taking a random // sample. The goal is to come up with an estimate that is fast and // accurate for non-pathological geometry. If our estimates happen to be // wrong, the vector will still grow automatically - the main side effects // are that memory usage will be larger (by up to a factor of 3), and // constructing the index will be about 10% slower. // // Given a desired sample size, we choose equally spaced edges from // throughout the entire data set. We use a Bresenham-type algorithm to // choose the samples. const int kDesiredSampleSize = 10000; const int sample_interval = max(1, batch.num_edges / kDesiredSampleSize); // Initialize "edge_id" to be midway through the first sample interval. // Because samples are equally spaced the actual sample size may differ // slightly from the desired sample size. int edge_id = sample_interval / 2; const int actual_sample_size = (batch.num_edges + edge_id) / sample_interval; int face_count[6] = { 0, 0, 0, 0, 0, 0 }; if (pending_removals_) { for (const auto& item : *pending_removals_) { const S2Shape* shape = item.shape.get(); edge_id += shape->num_edges(); while (edge_id >= sample_interval) { edge_id -= sample_interval; face_count[S2::GetFace(shape->edge(edge_id).v0)] += 1; } } } for (auto begin = batch.begin; begin < batch.end; ++begin.shape_id, begin.edge_id = 0) { const S2Shape* shape = this->shape(begin.shape_id); if (shape == nullptr) continue; // Already removed. int edges_end = begin.shape_id == batch.end.shape_id ? batch.end.edge_id : shape->num_edges(); edge_id += edges_end - begin.edge_id; while (edge_id >= sample_interval) { edge_id -= sample_interval; // For speed, we only count the face containing one endpoint of the // edge. In general the edge could span all 6 faces (with padding), but // it's not worth the expense to compute this more accurately. face_count[S2::GetFace(shape->edge(edge_id + begin.edge_id).v0)] += 1; } } // Now given the raw face counts, compute a confidence interval such that we // will be unlikely to allocate too little space. Computing accurate // binomial confidence intervals is expensive and not really necessary. // Instead we use a simple approximation: // - For any face with at least 1 sample, we use at least a 4-sigma // confidence interval. (The chosen width is adequate for the worst case // accuracy, which occurs when the face contains approximately 50% of the // edges.) Assuming that our sample is representative, the probability of // reserving too little space is approximately 1 in 30,000. // - For faces with no samples at all, we don't bother reserving space. // It is quite likely that such faces are truly empty, so we save time // and memory this way. If the face does contain some edges, there will // only be a few so it is fine to let the vector grow automatically. // On average, we reserve 2% extra space for each face that has geometry // (which could be up to 12% extra space overall, but typically 2%). // kMaxSemiWidth is the maximum semi-width over all probabilities p of a // 4-sigma binomial confidence interval with a sample size of 10,000. const double kMaxSemiWidth = 0.02; // First estimate the total amount of memory we are about to allocate. double multiplier = 1.0; for (int face = 0; face < 6; ++face) { if (face_count[face] != 0) multiplier += kMaxSemiWidth; } face_edge_usage = multiplier * batch.num_edges * sizeof(FaceEdge); if (!mem_tracker_.TallyTemp(face_edge_usage + other_usage)) { return; } const double sample_ratio = 1.0 / actual_sample_size; for (int face = 0; face < 6; ++face) { if (face_count[face] == 0) continue; double fraction = sample_ratio * face_count[face] + kMaxSemiWidth; all_edges[face].reserve(fraction * batch.num_edges); } } // Clips the edges of the given shape to the six cube faces, add the clipped // edges to "all_edges", and start tracking its interior if necessary. void MutableS2ShapeIndex::AddShape(const S2Shape* shape, int shape_id, int edges_begin, int edges_end, vector all_edges[6], InteriorTracker* tracker) const { // Construct a template for the edges to be added. FaceEdge edge; edge.shape_id = shape_id; edge.has_interior = false; if (shape->dimension() == 2) { // To add a single shape with an interior over multiple batches, we first // add all the edges without tracking the interior. After all edges have // been added, the interior is updated in a separate step by setting the // contains_center() flags appropriately. if (edges_begin > 0 || edges_end < shape->num_edges()) { tracker->set_partial_shape_id(edge.shape_id); } else { edge.has_interior = true; tracker->AddShape( edge.shape_id, s2shapeutil::ContainsBruteForce(*shape, tracker->focus())); } } for (int e = edges_begin; e < edges_end; ++e) { edge.edge_id = e; edge.edge = shape->edge(e); edge.max_level = GetEdgeMaxLevel(edge.edge); AddFaceEdge(&edge, all_edges); } } void MutableS2ShapeIndex::RemoveShape(const S2Shape* shape, int shape_id, vector all_edges[6], InteriorTracker* tracker) const { FaceEdge edge; edge.edge_id = -1; // Not used or needed for removed edges. edge.shape_id = shape_id; edge.has_interior = (shape->dimension() == 2); if (edge.has_interior) { // Use a stale iterator to avoid triggering a recursive index update. // This is much faster than using ContainsBruteForce(), since the removed // shape is already in the index. Iterator it; bool inside = false; it.InitStale(this, InitialPosition::BEGIN); if (it.Locate(InteriorTracker::Origin())) { const S2ClippedShape* clipped = it.cell().find_clipped(shape_id); if (clipped != nullptr) { inside = clipped->contains_center(); S2CopyingEdgeCrosser x(it.id().ToPoint(), InteriorTracker::Origin()); for (int i = 0; i < clipped->num_edges(); ++i) { auto edge = shape->edge(clipped->edge(i)); inside ^= x.EdgeOrVertexCrossing(edge.v0, edge.v1); } } } tracker->AddShape(shape_id, inside); } for (int e = 0; e < shape->num_edges(); ++e) { edge.edge = shape->edge(e); edge.max_level = GetEdgeMaxLevel(edge.edge); AddFaceEdge(&edge, all_edges); } } void MutableS2ShapeIndex::FinishPartialShape(int shape_id) { if (shape_id < 0) return; // The partial shape did not have an interior. const S2Shape* shape = this->shape(shape_id); // Filling in the interior of a partial shape can grow the cell_map_ // significantly, however the new cells have just one shape and no edges. // The following is a rough estimate of how much extra memory is needed // based on experiments. It assumes that one new cell is required for every // 10 shape edges, and that the cell map uses 50% more space than necessary // for the new entries because they are inserted between existing entries // (which means that the btree nodes are not full). if (mem_tracker_.is_active()) { const int64_t new_usage = SpaceUsed() - mem_tracker_.client_usage_bytes() + 0.1 * shape->num_edges() * (1.5 * sizeof(CellMap::value_type) + sizeof(S2ShapeIndexCell) + sizeof(S2ClippedShape)); if (!mem_tracker_.TallyTemp(new_usage)) return; } // All the edges of the partial shape have already been indexed, now we just // need to set the contains_center() flags appropriately. We use a fresh // InteriorTracker for this purpose since we don't want to continue tracking // the interior state of any other shapes in this batch. // // We have implemented this below in the simplest way possible, namely by // scanning through the entire index. In theory it would be more efficient // to keep track of the set of index cells that were modified when the // partial shape's edges were added, and then visit only those cells. // However in practice any shape that is added over multiple batches is // likely to occupy most or all of the index anyway, so it is faster and // simpler to just iterate through the entire index. // // "tmp_edges" below speeds up large polygon index construction by 3-12%. vector tmp_edges; // Temporary storage. InteriorTracker tracker; tracker.AddShape(shape_id, s2shapeutil::ContainsBruteForce(*shape, tracker.focus())); S2CellId begin = S2CellId::Begin(S2CellId::kMaxLevel); for (CellMap::iterator index_it = cell_map_.begin(); ; ++index_it) { if (!tracker.shape_ids().empty()) { // Check whether we need to add new cells that are entirely contained by // the partial shape. S2CellId fill_end = (index_it != cell_map_.end()) ? index_it->first.range_min() : S2CellId::End(S2CellId::kMaxLevel); if (begin != fill_end) { for (S2CellId cellid : S2CellUnion::FromBeginEnd(begin, fill_end)) { auto cell = make_unique(); S2ClippedShape* clipped = cell->add_shapes(1); clipped->Init(shape_id, 0); clipped->set_contains_center(true); index_it = cell_map_.insert(index_it, make_pair(cellid, std::move(cell))); ++index_it; } } } if (index_it == cell_map_.end()) break; // Now check whether the current index cell needs to be updated. S2CellId cellid = index_it->first; S2ShapeIndexCell& cell = *index_it->second; int n = cell.shapes_.size(); if (n > 0 && cell.shapes_[n - 1].shape_id() == shape_id) { // This cell contains edges of the partial shape. If the partial shape // contains the center of this cell, we must update the index. S2PaddedCell pcell(cellid, kCellPadding); if (!tracker.at_cellid(cellid)) { tracker.MoveTo(pcell.GetEntryVertex()); } tracker.DrawTo(pcell.GetCenter()); S2ClippedShape* clipped = &cell.shapes_[n - 1]; int num_edges = clipped->num_edges(); ABSL_DCHECK_GT(num_edges, 0); for (int i = 0; i < num_edges; ++i) { tmp_edges.push_back(shape->edge(clipped->edge(i))); } for (const auto& edge : tmp_edges) { tracker.TestEdge(shape_id, edge); } if (!tracker.shape_ids().empty()) { // The partial shape contains the center of this index cell. clipped->set_contains_center(true); } tracker.DrawTo(pcell.GetExitVertex()); for (const auto& edge : tmp_edges) { tracker.TestEdge(shape_id, edge); } tracker.set_next_cellid(cellid.next()); tmp_edges.clear(); } else if (!tracker.shape_ids().empty()) { // The partial shape contains the center of an existing index cell that // does not intersect any of its edges. S2ClippedShape* clipped = cell.add_shapes(1); clipped->Init(shape_id, 0); clipped->set_contains_center(true); } begin = cellid.range_max().next(); } } inline void MutableS2ShapeIndex::AddFaceEdge( FaceEdge* edge, vector all_edges[6]) const { // Fast path: both endpoints are on the same face, and are far enough from // the edge of the face that don't intersect any (padded) adjacent face. int a_face = S2::GetFace(edge->edge.v0); if (a_face == S2::GetFace(edge->edge.v1)) { S2::ValidFaceXYZtoUV(a_face, edge->edge.v0, &edge->a); S2::ValidFaceXYZtoUV(a_face, edge->edge.v1, &edge->b); const double kMaxUV = 1 - kCellPadding; if (fabs(edge->a[0]) <= kMaxUV && fabs(edge->a[1]) <= kMaxUV && fabs(edge->b[0]) <= kMaxUV && fabs(edge->b[1]) <= kMaxUV) { all_edges[a_face].push_back(*edge); return; } } // Otherwise we simply clip the edge to all six faces. for (int face = 0; face < 6; ++face) { if (S2::ClipToPaddedFace(edge->edge.v0, edge->edge.v1, face, kCellPadding, &edge->a, &edge->b)) { all_edges[face].push_back(*edge); } } } // Returns the first level for which the given edge will be considered "long", // i.e. it will not count towards the max_edges_per_cell() limit. int MutableS2ShapeIndex::GetEdgeMaxLevel(const S2Shape::Edge& edge) const { // Compute the maximum cell edge length for which this edge is considered // "long". The calculation does not need to be perfectly accurate, so we // use Norm() rather than Angle() for speed. double max_cell_edge = ((edge.v0 - edge.v1).Norm() * absl::GetFlag(FLAGS_s2shape_index_cell_size_to_long_edge_ratio)); // Now return the first level encountered during subdivision where the // average cell edge length at that level is at most "max_cell_edge". return S2::kAvgEdge.GetLevelForMaxValue(max_cell_edge); } // EdgeAllocator provides temporary storage for new ClippedEdges that are // created during indexing. It is essentially a stack model, where edges are // allocated as the recursion does down and freed as it comes back up. // // It also provides a mutable vector of FaceEdges that is used when // incrementally updating the index (see AbsorbIndexCell). class MutableS2ShapeIndex::EdgeAllocator { public: EdgeAllocator() = default; // Return a pointer to a newly allocated edge. The EdgeAllocator // retains ownership. ClippedEdge* NewClippedEdge() { if (size_ == clipped_edges_.size()) { clipped_edges_.emplace_back(new ClippedEdge); } return clipped_edges_[size_++].get(); } // Return the number of allocated edges. size_t size() const { return size_; } // Reset the allocator to only contain the first "size" allocated edges. void Reset(size_t size) { size_ = size; } vector* mutable_face_edges() { return &face_edges_; } private: // We can't use vector because edges are not allowed to move // once they have been allocated. Instead we keep a pool of allocated edges // that are all deleted together at the end. size_t size_ = 0; vector> clipped_edges_; // On the other hand, we can use vector because they are allocated // only at one level during the recursion (namely, the level at which we // absorb an existing index cell). vector face_edges_; EdgeAllocator(const EdgeAllocator&) = delete; void operator=(const EdgeAllocator&) = delete; }; // Given a face and a vector of edges that intersect that face, add or remove // all the edges from the index. (An edge is added if shapes_[id] is not // nullptr, and removed otherwise.) void MutableS2ShapeIndex::UpdateFaceEdges(int face, absl::Span face_edges, InteriorTracker* tracker) { int num_edges = face_edges.size(); if (num_edges == 0 && tracker->shape_ids().empty()) return; // Create the initial ClippedEdge for each FaceEdge. Additional clipped // edges are created when edges are split between child cells. We create // two arrays, one containing the edge data and another containing pointers // to those edges, so that during the recursion we only need to copy // pointers in order to propagate an edge to the correct child. vector clipped_edge_storage; vector clipped_edges; clipped_edge_storage.reserve(num_edges); clipped_edges.reserve(num_edges); R2Rect bound = R2Rect::Empty(); for (int e = 0; e < num_edges; ++e) { ClippedEdge clipped; clipped.face_edge = &face_edges[e]; clipped.bound = R2Rect::FromPointPair(face_edges[e].a, face_edges[e].b); clipped_edge_storage.push_back(clipped); clipped_edges.push_back(&clipped_edge_storage.back()); bound.AddRect(clipped.bound); } // Construct the initial face cell containing all the edges, and then update // all the edges in the index recursively. EdgeAllocator alloc; S2CellId face_id = S2CellId::FromFace(face); S2PaddedCell pcell(face_id, kCellPadding); // "disjoint_from_index" means that the current cell being processed (and // all its descendants) are not already present in the index. It is set to // true during the recursion whenever we detect that the current cell is // disjoint from the index. We could save a tiny bit of work by setting // this flag to true here on the very first update, however currently there // is no easy way to check that. (It's not sufficient to test whether // cell_map_.empty() or pending_additions_begin_ == 0.) bool disjoint_from_index = false; if (num_edges > 0) { S2CellId shrunk_id = ShrinkToFit(pcell, bound); if (shrunk_id != pcell.id()) { // All the edges are contained by some descendant of the face cell. We // can save a lot of work by starting directly with that cell, but if we // are in the interior of at least one shape then we need to create // index entries for the cells we are skipping over. SkipCellRange(face_id.range_min(), shrunk_id.range_min(), tracker, &alloc, disjoint_from_index); pcell = S2PaddedCell(shrunk_id, kCellPadding); UpdateEdges(pcell, &clipped_edges, tracker, &alloc, disjoint_from_index); SkipCellRange(shrunk_id.range_max().next(), face_id.range_max().next(), tracker, &alloc, disjoint_from_index); return; } } // Otherwise (no edges, or no shrinking is possible), subdivide normally. UpdateEdges(pcell, &clipped_edges, tracker, &alloc, disjoint_from_index); } S2CellId MutableS2ShapeIndex::ShrinkToFit(const S2PaddedCell& pcell, const R2Rect& bound) const { S2CellId shrunk_id = pcell.ShrinkToFit(bound); if (shrunk_id != pcell.id()) { // Don't shrink any smaller than the existing index cells, since we need // to combine the new edges with those cells. Use InitStale() to avoid // applying updates recursively. Iterator iter; iter.InitStale(this); S2CellRelation r = iter.Locate(shrunk_id); if (r == S2CellRelation::INDEXED) { shrunk_id = iter.id(); } } return shrunk_id; } // Skip over the cells in the given range, creating index cells if we are // currently in the interior of at least one shape. void MutableS2ShapeIndex::SkipCellRange(S2CellId begin, S2CellId end, InteriorTracker* tracker, EdgeAllocator* alloc, bool disjoint_from_index) { // If we aren't in the interior of a shape, then skipping over cells is easy. if (tracker->shape_ids().empty()) return; // Otherwise generate the list of cell ids that we need to visit, and create // an index entry for each one. for (S2CellId skipped_id : S2CellUnion::FromBeginEnd(begin, end)) { vector clipped_edges; UpdateEdges(S2PaddedCell(skipped_id, kCellPadding), &clipped_edges, tracker, alloc, disjoint_from_index); } } // Given an edge and an interval "middle" along the v-axis, clip the edge // against the boundaries of "middle" and add the edge to the corresponding // children. /* static */ ABSL_ATTRIBUTE_ALWAYS_INLINE // ~8% faster inline void MutableS2ShapeIndex::ClipVAxis( const ClippedEdge* edge, const R1Interval& middle, vector child_edges[2], EdgeAllocator* alloc) { if (edge->bound[1].hi() <= middle.lo()) { // Edge is entirely contained in the lower child. child_edges[0].push_back(edge); } else if (edge->bound[1].lo() >= middle.hi()) { // Edge is entirely contained in the upper child. child_edges[1].push_back(edge); } else { // The edge bound spans both children. child_edges[0].push_back(ClipVBound(edge, 1, middle.hi(), alloc)); child_edges[1].push_back(ClipVBound(edge, 0, middle.lo(), alloc)); } } // Given a cell and a set of ClippedEdges whose bounding boxes intersect that // cell, add or remove all the edges from the index. Temporary space for // edges that need to be subdivided is allocated from the given EdgeAllocator. // "disjoint_from_index" is an optimization hint indicating that cell_map_ // does not contain any entries that overlap the given cell. void MutableS2ShapeIndex::UpdateEdges(const S2PaddedCell& pcell, vector* edges, InteriorTracker* tracker, EdgeAllocator* alloc, bool disjoint_from_index) { // Cases where an index cell is not needed should be detected before this. ABSL_DCHECK(!edges->empty() || !tracker->shape_ids().empty()); // This function is recursive with a maximum recursion depth of 30 // (S2CellId::kMaxLevel). Note that using an explicit stack does not seem // to be any faster based on profiling. // Incremental updates are handled as follows. All edges being added or // removed are combined together in "edges", and all shapes with interiors // are tracked using "tracker". We subdivide recursively as usual until we // encounter an existing index cell. At this point we "absorb" the index // cell as follows: // // - Edges and shapes that are being removed are deleted from "edges" and // "tracker". // - All remaining edges and shapes from the index cell are added to // "edges" and "tracker". // - Continue subdividing recursively, creating new index cells as needed. // - When the recursion gets back to the cell that was absorbed, we // restore "edges" and "tracker" to their previous state. // // Note that the only reason that we include removed shapes in the recursive // subdivision process is so that we can find all of the index cells that // contain those shapes efficiently, without maintaining an explicit list of // index cells for each shape (which would be expensive in terms of memory). bool index_cell_absorbed = false; if (!disjoint_from_index) { // There may be existing index cells contained inside "pcell". If we // encounter such a cell, we need to combine the edges being updated with // the existing cell contents by "absorbing" the cell. We use InitStale() // to avoid applying updates recursively. Iterator iter; iter.InitStale(this); S2CellRelation r = iter.Locate(pcell.id()); if (r == S2CellRelation::DISJOINT) { disjoint_from_index = true; } else if (r == S2CellRelation::INDEXED) { // Absorb the index cell by transferring its contents to "edges" and // deleting it. We also start tracking the interior of any new shapes. AbsorbIndexCell(pcell, iter, edges, tracker, alloc); index_cell_absorbed = true; disjoint_from_index = true; } else { ABSL_DCHECK_EQ(S2CellRelation::SUBDIVIDED, r); } } // If there are existing index cells below us, then we need to keep // subdividing so that we can merge with those cells. Otherwise, // MakeIndexCell checks if the number of edges is small enough, and creates // an index cell if possible (returning true when it does so). if (!disjoint_from_index || !MakeIndexCell(pcell, *edges, tracker)) { // Reserve space for the edges that will be passed to each child. This is // important since otherwise the running time is dominated by the time // required to grow the vectors. The amount of memory involved is // relatively small, so we simply reserve the maximum space for every child. vector child_edges[2][2]; // [i][j] int num_edges = edges->size(); for (int i = 0; i < 2; ++i) { for (int j = 0; j < 2; ++j) { child_edges[i][j].reserve(num_edges); } } // Remember the current size of the EdgeAllocator so that we can free any // edges that are allocated during edge splitting. size_t alloc_size = alloc->size(); // Compute the middle of the padded cell, defined as the rectangle in // (u,v)-space that belongs to all four (padded) children. By comparing // against the four boundaries of "middle" we can determine which children // each edge needs to be propagated to. const R2Rect& middle = pcell.middle(); // Build up a vector edges to be passed to each child cell. The (i,j) // directions are left (i=0), right (i=1), lower (j=0), and upper (j=1). // Note that the vast majority of edges are propagated to a single child. // This case is very fast, consisting of between 2 and 4 floating-point // comparisons and copying one pointer. (ClipVAxis is inline.) for (int e = 0; e < num_edges; ++e) { const ClippedEdge* edge = (*edges)[e]; if (edge->bound[0].hi() <= middle[0].lo()) { // Edge is entirely contained in the two left children. ClipVAxis(edge, middle[1], child_edges[0], alloc); } else if (edge->bound[0].lo() >= middle[0].hi()) { // Edge is entirely contained in the two right children. ClipVAxis(edge, middle[1], child_edges[1], alloc); } else if (edge->bound[1].hi() <= middle[1].lo()) { // Edge is entirely contained in the two lower children. child_edges[0][0].push_back(ClipUBound(edge, 1, middle[0].hi(), alloc)); child_edges[1][0].push_back(ClipUBound(edge, 0, middle[0].lo(), alloc)); } else if (edge->bound[1].lo() >= middle[1].hi()) { // Edge is entirely contained in the two upper children. child_edges[0][1].push_back(ClipUBound(edge, 1, middle[0].hi(), alloc)); child_edges[1][1].push_back(ClipUBound(edge, 0, middle[0].lo(), alloc)); } else { // The edge bound spans all four children. The edge itself intersects // either three or four (padded) children. const ClippedEdge* left = ClipUBound(edge, 1, middle[0].hi(), alloc); ClipVAxis(left, middle[1], child_edges[0], alloc); const ClippedEdge* right = ClipUBound(edge, 0, middle[0].lo(), alloc); ClipVAxis(right, middle[1], child_edges[1], alloc); } } // Free any memory reserved for children that turned out to be empty. This // step is cheap and reduces peak memory usage by about 10% when building // large indexes (> 10M edges). for (int i = 0; i < 2; ++i) { for (int j = 0; j < 2; ++j) { if (child_edges[i][j].empty()) { vector().swap(child_edges[i][j]); } } } // Now recursively update the edges in each child. We call the children in // increasing order of S2CellId so that when the index is first constructed, // all insertions into cell_map_ are at the end (which is much faster). for (int pos = 0; pos < 4; ++pos) { int i, j; pcell.GetChildIJ(pos, &i, &j); if (!child_edges[i][j].empty() || !tracker->shape_ids().empty()) { UpdateEdges(S2PaddedCell(pcell, i, j), &child_edges[i][j], tracker, alloc, disjoint_from_index); } } // Free any temporary edges that were allocated during clipping. alloc->Reset(alloc_size); } if (index_cell_absorbed) { // Restore the state for any edges being removed that we are tracking. tracker->RestoreStateBefore(pending_additions_begin_); } } // Given an edge, clip the given endpoint (lo=0, hi=1) of the u-axis so that // it does not extend past the given value. /* static */ const MutableS2ShapeIndex::ClippedEdge* MutableS2ShapeIndex::ClipUBound(const ClippedEdge* edge, int u_end, double u, EdgeAllocator* alloc) { // First check whether the edge actually requires any clipping. (Sometimes // this method is called when clipping is not necessary, e.g. when one edge // endpoint is in the overlap area between two padded child cells.) if (u_end == 0) { if (edge->bound[0].lo() >= u) return edge; } else { if (edge->bound[0].hi() <= u) return edge; } // We interpolate the new v-value from the endpoints of the original edge. // This has two advantages: (1) we don't need to store the clipped endpoints // at all, just their bounding box; and (2) it avoids the accumulation of // roundoff errors due to repeated interpolations. The result needs to be // clamped to ensure that it is in the appropriate range. const FaceEdge& e = *edge->face_edge; double v = edge->bound[1].Project( S2::InterpolateDouble(u, e.a[0], e.b[0], e.a[1], e.b[1])); // Determine which endpoint of the v-axis bound to update. If the edge // slope is positive we update the same endpoint, otherwise we update the // opposite endpoint. int v_end = u_end ^ ((e.a[0] > e.b[0]) != (e.a[1] > e.b[1])); return UpdateBound(edge, u_end, u, v_end, v, alloc); } // Given an edge, clip the given endpoint (lo=0, hi=1) of the v-axis so that // it does not extend past the given value. /* static */ const MutableS2ShapeIndex::ClippedEdge* MutableS2ShapeIndex::ClipVBound(const ClippedEdge* edge, int v_end, double v, EdgeAllocator* alloc) { // See comments in ClipUBound. if (v_end == 0) { if (edge->bound[1].lo() >= v) return edge; } else { if (edge->bound[1].hi() <= v) return edge; } const FaceEdge& e = *edge->face_edge; double u = edge->bound[0].Project( S2::InterpolateDouble(v, e.a[1], e.b[1], e.a[0], e.b[0])); int u_end = v_end ^ ((e.a[0] > e.b[0]) != (e.a[1] > e.b[1])); return UpdateBound(edge, u_end, u, v_end, v, alloc); } // Given an edge and two bound endpoints that need to be updated, allocate and // return a new edge with the updated bound. /* static */ inline const MutableS2ShapeIndex::ClippedEdge* MutableS2ShapeIndex::UpdateBound(const ClippedEdge* edge, int u_end, double u, int v_end, double v, EdgeAllocator* alloc) { ClippedEdge* clipped = alloc->NewClippedEdge(); clipped->face_edge = edge->face_edge; clipped->bound[0][u_end] = u; clipped->bound[1][v_end] = v; clipped->bound[0][1-u_end] = edge->bound[0][1-u_end]; clipped->bound[1][1-v_end] = edge->bound[1][1-v_end]; ABSL_DCHECK(!clipped->bound.is_empty()); ABSL_DCHECK(edge->bound.Contains(clipped->bound)); return clipped; } // Absorb an index cell by transferring its contents to "edges" and/or // "tracker", and then delete this cell from the index. If "edges" includes // any edges that are being removed, this method also updates their // InteriorTracker state to correspond to the exit vertex of this cell, and // saves the InteriorTracker state by calling SaveAndClearStateBefore(). It // is the caller's responsibility to restore this state by calling // RestoreStateBefore() when processing of this cell is finished. void MutableS2ShapeIndex::AbsorbIndexCell(const S2PaddedCell& pcell, const Iterator& iter, vector* edges, InteriorTracker* tracker, EdgeAllocator* alloc) { ABSL_DCHECK_EQ(pcell.id(), iter.id()); // When we absorb a cell, we erase all the edges that are being removed. // However when we are finished with this cell, we want to restore the state // of those edges (since that is how we find all the index cells that need // to be updated). The edges themselves are restored automatically when // UpdateEdges returns from its recursive call, but the InteriorTracker // state needs to be restored explicitly. // // Here we first update the InteriorTracker state for removed edges to // correspond to the exit vertex of this cell, and then save the // InteriorTracker state. This state will be restored by UpdateEdges when // it is finished processing the contents of this cell. (Note in the test // below that removed edges are always sorted before added edges.) if (tracker->is_active() && !edges->empty() && is_shape_being_removed((*edges)[0]->face_edge->shape_id)) { // We probably need to update the InteriorTracker. ("Probably" because // it's possible that all shapes being removed do not have interiors.) if (!tracker->at_cellid(pcell.id())) { tracker->MoveTo(pcell.GetEntryVertex()); } tracker->DrawTo(pcell.GetExitVertex()); tracker->set_next_cellid(pcell.id().next()); for (const ClippedEdge* edge : *edges) { const FaceEdge* face_edge = edge->face_edge; if (!is_shape_being_removed(face_edge->shape_id)) { break; // All shapes being removed come first. } if (face_edge->has_interior) { tracker->TestEdge(face_edge->shape_id, face_edge->edge); } } } // Save the state of the edges being removed so that it can be restored when // we are finished processing this cell and its children. Below we not only // remove those edges but also add new edges whose state only needs to be // tracked within this subtree. We don't need to save the state of the // edges being added because they aren't being removed from "edges" and will // therefore be updated normally as we visit this cell and its children. tracker->SaveAndClearStateBefore(pending_additions_begin_); // Create a FaceEdge for each edge in this cell that isn't being removed. vector* face_edges = alloc->mutable_face_edges(); face_edges->clear(); bool tracker_moved = false; const S2ShapeIndexCell& cell = iter.cell(); for (int s = 0; s < cell.num_clipped(); ++s) { const S2ClippedShape& clipped = cell.clipped(s); int shape_id = clipped.shape_id(); const S2Shape* shape = this->shape(shape_id); if (shape == nullptr) continue; // This shape is being removed. int num_edges = clipped.num_edges(); // If this shape has an interior, start tracking whether we are inside the // shape. UpdateEdges() wants to know whether the entry vertex of this // cell is inside the shape, but we only know whether the center of the // cell is inside the shape, so we need to test all the edges against the // line segment from the cell center to the entry vertex. FaceEdge edge; edge.shape_id = shape_id; edge.has_interior = (shape->dimension() == 2 && shape_id != tracker->partial_shape_id()); if (edge.has_interior) { tracker->AddShape(shape_id, clipped.contains_center()); // There might not be any edges in this entire cell (i.e., it might be // in the interior of all shapes), so we delay updating the tracker // until we see the first edge. if (!tracker_moved && num_edges > 0) { tracker->MoveTo(pcell.GetCenter()); tracker->DrawTo(pcell.GetEntryVertex()); tracker->set_next_cellid(pcell.id()); tracker_moved = true; } } for (int i = 0; i < num_edges; ++i) { int e = clipped.edge(i); edge.edge_id = e; edge.edge = shape->edge(e); edge.max_level = GetEdgeMaxLevel(edge.edge); if (edge.has_interior) tracker->TestEdge(shape_id, edge.edge); if (!S2::ClipToPaddedFace(edge.edge.v0, edge.edge.v1, pcell.id().face(), kCellPadding, &edge.a, &edge.b)) { ABSL_LOG(DFATAL) << "Invariant failure in MutableS2ShapeIndex"; } face_edges->push_back(edge); } } // Now create a ClippedEdge for each FaceEdge, and put them in "new_edges". vector new_edges; for (const FaceEdge& face_edge : *face_edges) { ClippedEdge* clipped = alloc->NewClippedEdge(); clipped->face_edge = &face_edge; clipped->bound = S2::GetClippedEdgeBound(face_edge.a, face_edge.b, pcell.bound()); new_edges.push_back(clipped); } // Discard any edges from "edges" that are being removed, and append the // remainder to "new_edges". (This keeps the edges sorted by shape id.) for (size_t i = 0; i < edges->size(); ++i) { const ClippedEdge* clipped = (*edges)[i]; if (!is_shape_being_removed(clipped->face_edge->shape_id)) { new_edges.insert(new_edges.end(), edges->begin() + i, edges->end()); break; } } // Update the edge list and delete this cell from the index. edges->swap(new_edges); cell_map_.erase(pcell.id()); } // Attempt to build an index cell containing the given edges, and return true // if successful. (Otherwise the edges should be subdivided further.) bool MutableS2ShapeIndex::MakeIndexCell(const S2PaddedCell& pcell, const vector& edges, InteriorTracker* tracker) { if (edges.empty() && tracker->shape_ids().empty()) { // No index cell is needed. (In most cases this situation is detected // before we get to this point, but this can happen when all shapes in a // cell are removed.) return true; } // We can show using amortized analysis that the total index size is // // O(c1 * n + c2 * (1 - f) / f * n) // // where n is the number of input edges (and where we also count an "edge" // for each shape with an interior but no edges), f is the value of // FLAGS_s2shape_index_min_short_edge_fraction, and c1 and c2 are constants // where c2 is about 20 times larger than c1. // // First observe that the space used by a MutableS2ShapeIndex is // proportional to the space used by all of its index cells, and the space // used by an S2ShapeIndexCell is proportional to the number of edges that // intersect that cell plus the number of shapes that contain the entire // cell ("containing shapes"). Define an "index entry" as an intersecting // edge or containing shape stored by an index cell. Our goal is then to // bound the number of index entries. // // We divide the index entries into two groups. An index entry is "short" // if it represents an edge that was considered short in that index cell's // parent, and "long" otherwise. (Note that the long index entries also // include the containing shapes mentioned above.) We then bound the // maximum number of both types of index entries by associating them with // edges that were considered short in those index cells' parents. // // First consider the short index entries for a given edge E. Let S be the // set of index cells that intersect E and where E was considered short in // those index cells' parents. Since E was short in each parent cell, the // width of those parent cells is at least some fraction "g" of E's length // (as controlled by FLAGS_s2shape_index_cell_size_to_long_edge_ratio). // Therefore the minimum width of each cell in S is also at least some // fraction of E's length (i.e., g / 2). This implies that there are at most // a constant number c1 of such cells, since they all intersect E and do not // overlap, which means that there are at most (c1 * n) short entries in // total. // // With index_cell_size_to_long_edge_ratio = 1.0 (the default value), it can // be shown that c1 = 10. In other words, it is not possible for a given // edge to intersect more than 10 index cells where it was considered short // in those cells' parents. The value of c1 can be reduced as low c1 = 4 by // increasing index_cell_size_to_long_edge_ratio to about 3.1. (The reason // the minimum value is 3.1 rather than 2.0 is that this ratio is defined in // terms of the average edge length of cells at a given level, rather than // their minimum width, and 2 * (S2::kAvgEdge / S2::kMinWidth) ~= 3.1.) // // Next we consider the long index entries. Let c2 be the maximum number of // index cells where a given edge E was considered short in those cells' // parents. (Unlike the case above, we do not require that these cells // intersect E.) Because the minimum width of each parent cell is at least // some fraction of E's length and the parent cells at a given level do not // overlap, there can be at most a small constant number of index cells at // each level where E is considered short in those cells' parents. For // example, consider a very short edge E that intersects the midpoint of a // cell edge at level 0. There are 16 cells at level 30 where E was // considered short in the parent cell, 12 cells at each of levels 29..2, and // 4 cells at levels 1 and 0 (pretending that all 6 face cells share a common // "parent"). This yields a total of c2 = 360 index cells. This is actually // the worst case for index_cell_size_to_long_edge_ratio >= 3.1; with the // default value of 1.0 it is possible to have a few more index cells at // levels 29 and 30, for a maximum of c2 = 366 index cells. // // The code below subdivides a given cell only if // // s > f * (s + l) // // where "f" is the min_short_edge_fraction parameter, "s" is the number of // short edges that intersect the cell, and "l" is the number of long edges // that intersect the cell plus an upper bound on the number of shapes that // contain the entire cell. (It is an upper bound rather than an exact count // because we use the number of shapes that contain an arbitrary vertex of // the cell.) Note that the number of long index entries in each child of // this cell is at most "l" because no child intersects more edges than its // parent or is entirely contained by more shapes than its parent. // // The inequality above can be rearranged to give // // l < s * (1 - f) / f // // This says that each long index entry in a child cell can be associated // with at most (1 - f) / f edges that were considered short when the parent // cell was subdivided. Furthermore we know that there are at most c2 index // cells where a given edge was considered short in the parent cell. Since // there are only n edges in total, this means that the maximum number of // long index entries is at most // // c2 * (1 - f) / f * n // // and putting this together with the result for short index entries gives // the desired bound. // // There are a variety of ways to make this bound tighter, e.g. when "n" is // relatively small. For example when the indexed geometry satisfies the // requirements of S2BooleanOperation (i.e., shape interiors are disjoint) // and the min_short_edge_fraction parameter is not too large, then the // constant c2 above is only about half as big (i.e., c2 ~= 180). This is // because the worst case under these circumstances requires having many // shapes whose interiors overlap. // Continue subdividing if the proposed index cell would contain too many // edges that are "short" relative to its size (as controlled by the // FLAGS_s2shape_index_cell_size_to_long_edge_ratio parameter). Usually "too // many" means more than options_.max_edges_per_cell(), but this value might // be increased if the cell has a lot of long edges and/or containing shapes. // This strategy ensures that the total index size is linear (see above). if (edges.size() > static_cast(options_.max_edges_per_cell())) { int max_short_edges = max(options_.max_edges_per_cell(), static_cast( absl::GetFlag(FLAGS_s2shape_index_min_short_edge_fraction) * (edges.size() + tracker->shape_ids().size()))); int count = 0; for (const ClippedEdge* edge : edges) { count += (pcell.level() < edge->face_edge->max_level); if (count > max_short_edges) return false; } } // Possible optimization: Continue subdividing as long as exactly one child // of "pcell" intersects the given edges. This can be done by finding the // bounding box of all the edges and calling ShrinkToFit(): // // S2CellId cellid = pcell.ShrinkToFit(GetRectBound(edges)); // // Currently this is not beneficial; it slows down construction by 4-25% // (mainly computing the union of the bounding rectangles) and also slows // down queries (since more recursive clipping is required to get down to // the level of a spatial index cell). But it may be worth trying again // once "contains_center" is computed and all algorithms are modified to // take advantage of it. // We update the InteriorTracker as follows. For every S2Cell in the index // we construct two edges: one edge from entry vertex of the cell to its // center, and one from the cell center to its exit vertex. Here "entry" // and "exit" refer the S2CellId ordering, i.e. the order in which points // are encountered along the S2 space-filling curve. The exit vertex then // becomes the entry vertex for the next cell in the index, unless there are // one or more empty intervening cells, in which case the InteriorTracker // state is unchanged because the intervening cells have no edges. // Shift the InteriorTracker focus point to the center of the current cell. if (tracker->is_active() && !edges.empty()) { if (!tracker->at_cellid(pcell.id())) { tracker->MoveTo(pcell.GetEntryVertex()); } tracker->DrawTo(pcell.GetCenter()); TestAllEdges(edges, tracker); } // Allocate and fill a new index cell. To get the total number of shapes we // need to merge the shapes associated with the intersecting edges together // with the shapes that happen to contain the cell center. const ShapeIdSet& cshape_ids = tracker->shape_ids(); int num_shapes = CountShapes(edges, cshape_ids); auto cell = make_unique(); S2ClippedShape* base = cell->add_shapes(num_shapes); // To fill the index cell we merge the two sources of shapes: "edge shapes" // (those that have at least one edge that intersects this cell), and // "containing shapes" (those that contain the cell center). We keep track // of the index of the next intersecting edge and the next containing shape // as we go along. Both sets of shape ids are already sorted. size_t enext = 0; ShapeIdSet::const_iterator cnext = cshape_ids.begin(); for (int i = 0; i < num_shapes; ++i) { S2ClippedShape* clipped = base + i; int eshape_id = num_shape_ids(), cshape_id = eshape_id; // Sentinels if (enext != edges.size()) { eshape_id = edges[enext]->face_edge->shape_id; } if (cnext != cshape_ids.end()) { cshape_id = *cnext; } int ebegin = enext; if (cshape_id < eshape_id) { // The entire cell is in the shape interior. clipped->Init(cshape_id, 0); clipped->set_contains_center(true); ++cnext; } else { // Count the number of edges for this shape and allocate space for them. while (enext < edges.size() && edges[enext]->face_edge->shape_id == eshape_id) { ++enext; } clipped->Init(eshape_id, enext - ebegin); for (size_t e = ebegin; e < enext; ++e) { clipped->set_edge(e - ebegin, edges[e]->face_edge->edge_id); } if (cshape_id == eshape_id) { clipped->set_contains_center(true); ++cnext; } } } // UpdateEdges() visits cells in increasing order of S2CellId, so during // initial construction of the index all insertions happen at the end. It // is much faster to give an insertion hint in this case. Otherwise the // hint doesn't do much harm. With more effort we could provide a hint even // during incremental updates, but this is probably not worth the effort. cell_map_.insert(cell_map_.end(), make_pair(pcell.id(), std::move(cell))); // Shift the InteriorTracker focus point to the exit vertex of this cell. if (tracker->is_active() && !edges.empty()) { tracker->DrawTo(pcell.GetExitVertex()); TestAllEdges(edges, tracker); tracker->set_next_cellid(pcell.id().next()); } return true; } // Call tracker->TestEdge() on all edges from shapes that have interiors. /* static */ void MutableS2ShapeIndex::TestAllEdges(const vector& edges, InteriorTracker* tracker) { for (const ClippedEdge* edge : edges) { const FaceEdge* face_edge = edge->face_edge; if (face_edge->has_interior) { tracker->TestEdge(face_edge->shape_id, face_edge->edge); } } } // Return the number of distinct shapes that are either associated with the // given edges, or that are currently stored in the InteriorTracker. /* static */ int MutableS2ShapeIndex::CountShapes(const vector& edges, const ShapeIdSet& cshape_ids) { int count = 0; int last_shape_id = -1; ShapeIdSet::const_iterator cnext = cshape_ids.begin(); // Next shape for (const ClippedEdge* edge : edges) { if (edge->face_edge->shape_id != last_shape_id) { ++count; last_shape_id = edge->face_edge->shape_id; // Skip over any containing shapes up to and including this one, // updating "count" appropriately. for (; cnext != cshape_ids.end(); ++cnext) { if (*cnext > last_shape_id) break; if (*cnext < last_shape_id) ++count; } } } // Count any remaining containing shapes. count += (cshape_ids.end() - cnext); return count; } size_t MutableS2ShapeIndex::SpaceUsed() const { size_t size = sizeof(*this); size += shapes_.capacity() * sizeof(unique_ptr); // cell_map_ itself is already included in sizeof(*this). size += cell_map_.bytes_used() - sizeof(cell_map_); size += cell_map_.size() * sizeof(S2ShapeIndexCell); Iterator it; for (it.InitStale(this, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { const S2ShapeIndexCell& cell = it.cell(); size += cell.shapes_.capacity() * sizeof(S2ClippedShape); for (int s = 0; s < cell.num_clipped(); ++s) { const S2ClippedShape& clipped = cell.clipped(s); if (!clipped.is_inline()) { size += clipped.num_edges() * sizeof(int32_t); } } } if (pending_removals_ != nullptr) { size += sizeof(*pending_removals_); size += pending_removals_->capacity() * sizeof(PendingRemoval); } return size; } void MutableS2ShapeIndex::Encode(Encoder* encoder) const { // The version number is encoded in 2 bits, under the assumption that by the // time we need 5 versions the first version can be permanently retired. // This only saves 1 byte, but that's significant for very small indexes. encoder->Ensure(Varint::kMax64); uint64_t max_edges = options_.max_edges_per_cell(); encoder->put_varint64(max_edges << 2 | kCurrentEncodingVersionNumber); // The index will be built anyway when we iterate through it, but building // it in advance lets us size the cell_ids vector correctly. ForceBuild(); vector cell_ids; cell_ids.reserve(cell_map_.size()); s2coding::StringVectorEncoder encoded_cells; for (Iterator it(this, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { cell_ids.push_back(it.id()); it.cell().Encode(num_shape_ids(), encoded_cells.AddViaEncoder()); } s2coding::EncodeS2CellIdVector(cell_ids, encoder); encoded_cells.Encode(encoder); } bool MutableS2ShapeIndex::Init(Decoder* decoder, const ShapeFactory& shape_factory) { Clear(); uint64_t max_edges_version; if (!decoder->get_varint64(&max_edges_version)) return false; int version = max_edges_version & 3; if (version != kCurrentEncodingVersionNumber) return false; options_.set_max_edges_per_cell(max_edges_version >> 2); uint32_t num_shapes = shape_factory.size(); shapes_.reserve(num_shapes); for (size_t shape_id = 0; shape_id < num_shapes; ++shape_id) { auto shape = shape_factory[shape_id]; shapes_.push_back(std::move(shape)); } s2coding::EncodedS2CellIdVector cell_ids; s2coding::EncodedStringVector encoded_cells; if (!cell_ids.Init(decoder)) return false; if (!encoded_cells.Init(decoder)) return false; for (size_t i = 0; i < cell_ids.size(); ++i) { S2CellId id = cell_ids[i]; auto cell = make_unique(); Decoder cell_decoder = encoded_cells.GetDecoder(i); if (!cell->Decode(num_shapes, &cell_decoder)) { return false; } cell_map_.insert(cell_map_.end(), make_pair(id, std::move(cell))); } return true; } src/s2/mutable_s2shape_index.h000066400000000000000000001013051524103652300166100ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_MUTABLE_S2SHAPE_INDEX_H_ #define S2_MUTABLE_S2SHAPE_INDEX_H_ #include #include #include #include #include #include #include "absl/base/thread_annotations.h" #include "absl/container/btree_map.h" #include "absl/flags/declare.h" #include "absl/log/absl_check.h" #include "absl/synchronization/mutex.h" #include "absl/types/span.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/base/spinlock.h" #include "s2/r1interval.h" #include "s2/r2rect.h" #include "s2/s2cell_id.h" #include "s2/s2cell_iterator.h" #include "s2/s2memory_tracker.h" #include "s2/s2point.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2shapeutil_shape_edge_id.h" #include "s2/util/coding/coder.h" class S2PaddedCell; namespace s2internal { // Hack to expose bytes_used. template class BTreeMap : public absl::btree_map { public: size_t bytes_used() const { return this->tree_.bytes_used(); } }; } // namespace s2internal // MutableS2ShapeIndex is a class for in-memory indexing of polygonal geometry. // The objects in the index are known as "shapes", and may consist of points, // polylines, and/or polygons, possibly overlapping. The index makes it very // fast to answer queries such as finding nearby shapes, measuring distances, // testing for intersection and containment, etc. It is one of several // implementations of the S2ShapeIndex interface (see EncodedS2ShapeIndex). // // MutableS2ShapeIndex allows not only building an index, but also updating it // incrementally by adding or removing shapes (hence its name). It is designed // to be compact; usually the index is smaller than the underlying geometry. // It is capable of indexing up to hundreds of millions of edges. The index is // also fast to construct. The index size and construction time are guaranteed // to be linear in the number of input edges. // // There are a number of built-in classes that work with S2ShapeIndex objects. // Generally these classes accept any collection of geometry that can be // represented by an S2ShapeIndex, i.e. any combination of points, polylines, // and polygons. Such classes include: // // - S2ContainsPointQuery: returns the shape(s) that contain a given point. // // - S2ClosestEdgeQuery: returns the closest edge(s) to a given point, edge, // S2CellId, or S2ShapeIndex. // // - S2CrossingEdgeQuery: returns the edge(s) that cross a given edge. // // - S2BooleanOperation: computes boolean operations such as union, // and boolean predicates such as containment. // // - S2ShapeIndexRegion: can be used together with S2RegionCoverer to // approximate geometry as a set of S2CellIds. // // - S2ShapeIndexBufferedRegion: computes approximations that have been // expanded by a given radius. // // Here is an example showing how to build an index for a set of polygons, and // then then determine which polygon(s) contain each of a set of query points: // // void TestContainment(const vector& points, // const vector& polygons) { // MutableS2ShapeIndex index; // for (auto polygon : polygons) { // index.Add(std::make_unique(polygon)); // } // S2ContainsPointQuery query(&index); // for (const auto& point : points) { // for (int shape_id : query.GetContainingShapeIds(point)) { // S2Polygon* polygon = polygons[shape_id]; // ... do something with (point, polygon) ... // } // } // } // // This example uses S2Polygon::Shape, which is one example of an S2Shape // object. S2Polyline and S2Loop also have nested Shape classes, and there are // additional S2Shape types defined in *_shape.h. // // Internally, MutableS2ShapeIndex is essentially a map from S2CellIds to the // set of shapes that intersect each S2CellId. It is adaptively refined to // ensure that no cell contains more than a small number of edges. // // For efficiency, updates are batched together and applied lazily on the // first subsequent query. Locking is used to ensure that MutableS2ShapeIndex // has the same thread-safety properties as "vector": const methods are // thread-safe, while non-const methods are not thread-safe. This means that // if one thread updates the index, you must ensure that no other thread is // reading or updating the index at the same time. // // MutableS2ShapeIndex has an Encode() method that allows the index to be // serialized. An encoded S2ShapeIndex can be decoded either into its // original form (MutableS2ShapeIndex) or into an EncodedS2ShapeIndex. The // key property of EncodedS2ShapeIndex is that it can be constructed // instantaneously, since the index is kept in its original encoded form. // Data is decoded only when an operation needs it. For example, to determine // which shapes(s) contain a given query point only requires decoding the data // in the S2ShapeIndexCell that contains that point. class MutableS2ShapeIndex final : public S2ShapeIndex { private: using CellMap = s2internal::BTreeMap>; public: // The amount by which cells are "padded" to compensate for numerical errors // when clipping line segments to cell boundaries. static const double kCellPadding; // Options that affect construction of the MutableS2ShapeIndex. class Options { public: Options(); // The maximum number of edges per cell. If a cell has more than this // many edges that are not considered "long" relative to the cell size, // then it is subdivided. (Whether an edge is considered "long" is // controlled by --s2shape_index_cell_size_to_long_edge_ratio flag.) // // Values between 10 and 50 represent a reasonable balance between memory // usage, construction time, and query time. Small values make queries // faster, while large values make construction faster and use less memory. // Values higher than 50 do not save significant additional memory, and // query times can increase substantially, especially for algorithms that // visit all pairs of potentially intersecting edges (such as polygon // validation), since this is quadratic in the number of edges per cell. // // Note that the *average* number of edges per cell is generally slightly // less than half of the maximum value defined here. // // Defaults to value given by --s2shape_index_default_max_edges_per_cell. int max_edges_per_cell() const { return max_edges_per_cell_; } void set_max_edges_per_cell(int max_edges_per_cell); private: int max_edges_per_cell_; }; // Creates a MutableS2ShapeIndex that uses the default option settings. // Option values may be changed by calling Init(). MutableS2ShapeIndex(); // Create a MutableS2ShapeIndex with the given options. explicit MutableS2ShapeIndex(const Options& options); ~MutableS2ShapeIndex() override; MutableS2ShapeIndex(MutableS2ShapeIndex&&) noexcept; MutableS2ShapeIndex& operator=(MutableS2ShapeIndex&&) noexcept; // Initialize a MutableS2ShapeIndex with the given options. This method may // only be called when the index is empty (i.e. newly created or Clear() has // just been called). May be called before or after set_memory_tracker(). void Init(const Options& options); const Options& options() const { return options_; } // Specifies that memory usage should be tracked and/or limited by the given // S2MemoryTracker. For example: // // S2MemoryTracker tracker; // tracker.set_limit(500 << 20); // 500 MB memory limit // MutableS2ShapeIndex index; // index.set_memory_tracker(&tracker); // // If the memory limit is exceeded, an appropriate status is returned in // memory_tracker()->error() and any partially built index is discarded // (equivalent to calling Minimize()). // // This method may be called multiple times in order to switch from one // memory tracker to another or stop memory tracking altogether (by passing // nullptr) in which case the memory usage due to this index is subtracted. // // REQUIRES: The lifetime of "tracker" must exceed the lifetime of the index // unless set_memory_tracker(nullptr) is called to stop memory // tracking before the index destructor is called. // // This implies that the S2MemoryTracker must be declared *before* // the MutableS2ShapeIndex in the example above. // // CAVEATS: // // - This method is not const and is therefore not thread-safe. // // - Does not track memory used by the S2Shapes in the index. // // - While the index representation itself is tracked very accurately, // the temporary data needed for index construction is tracked using // heuristics and may be underestimated or overestimated. // // - Temporary memory usage is typically 10x larger than the final index // size, however it can be reduced by specifying a suitable value for // FLAGS_s2shape_index_tmp_memory_budget (the default is 100 MB). If // more temporary memory than this is needed during construction, index // updates will be split into multiple batches in order to keep the // estimated temporary memory usage below this limit. // // - S2MemoryTracker::limit() has no effect on how much temporary memory // MutableS2ShapeIndex will attempt to use during index construction; it // simply causes an error to be returned when the limit would otherwise // be exceeded. If you set a memory limit smaller than 100MB and want to // reduce memory usage rather than simply generating an error then you // should also set FLAGS_s2shape_index_tmp_memory_budget appropriately. void set_memory_tracker(S2MemoryTracker* tracker); S2MemoryTracker* memory_tracker() const { return mem_tracker_.tracker(); } // The number of distinct shape ids that have been assigned. This equals // the number of shapes in the index provided that no shapes have ever been // removed. (Shape ids are not reused.) int num_shape_ids() const override { return static_cast(shapes_.size()); } // Returns a pointer to the shape with the given id, or nullptr if the shape // has been removed from the index. const S2Shape* shape(int id) const override { return shapes_[id].get(); } // Minimizes memory usage by requesting that any data structures that can be // rebuilt should be discarded. This method invalidates all iterators. // // Like all non-const methods, this method is not thread-safe. void Minimize() override; // Appends an encoded representation of the S2ShapeIndex to "encoder". // // This method does not encode the S2Shapes in the index; it is the client's // responsibility to encode them separately. For example: // // s2shapeutil::CompactEncodeTaggedShapes(index, encoder); // index.Encode(encoder); // // The encoded size is typically much smaller than the in-memory size. // Here are a few examples: // // Number of edges In-memory space used Encoded size (%) // -------------------------------------------------------------- // 8 192 8 4% // 768 18,264 2,021 11% // 3,784,212 80,978,992 17,039,020 21% // // The encoded form also has the advantage of being a contiguous block of // memory. // // REQUIRES: "encoder" uses the default constructor, so that its buffer // can be enlarged as necessary by calling Ensure(int). void Encode(Encoder* encoder) const override; // Decodes an S2ShapeIndex, returning true on success. // // This method does not decode the S2Shape objects in the index; this is // the responsibility of the client-provided function "shape_factory" // (see s2shapeutil_coding.h). Example usage: // // index.Init(decoder, s2shapeutil::LazyDecodeShapeFactory(decoder)); // // Note that the S2Shape vector must be encoded *before* the S2ShapeIndex in // this example. bool Init(Decoder* decoder, const ShapeFactory& shape_factory); class Iterator final : public IteratorBase { public: // Default constructor; must be followed by a call to Init(). Iterator() = default; // Constructs an iterator positioned as specified. By default iterators // are unpositioned, since this avoids an extra seek in this situation // where one of the seek methods (such as Locate) is immediately called. // // If you want to position the iterator at the beginning, e.g. in order to // loop through the entire index, do this instead: // // for (MutableS2ShapeIndex::Iterator it(&index, S2ShapeIndex::BEGIN); // !it.done(); it.Next()) { ... } explicit Iterator(const MutableS2ShapeIndex* index, InitialPosition pos = UNPOSITIONED); // Initializes an iterator for the given MutableS2ShapeIndex. This method // may also be called in order to restore an iterator to a valid state // after the underlying index has been updated (although it is usually // easier just to declare a new iterator whenever required, since iterator // construction is cheap). void Init(const MutableS2ShapeIndex* index, InitialPosition pos = UNPOSITIONED); // Initialize an iterator for the given MutableS2ShapeIndex without // applying any pending updates. This can be used to observe the actual // current state of the index without modifying it in any way. void InitStale(const MutableS2ShapeIndex* index, InitialPosition pos = UNPOSITIONED); S2CellId id() const override { S2CellId id = S2CellId::Sentinel(); if (!done()) { id = iter_->first; } return id; } const S2ShapeIndexCell& cell() const override { ABSL_DCHECK(!done()); return *iter_->second; } bool done() const override { return iter_ == end_; } // S2CellIterator API: void Begin() override; void Finish() override; void Next() override; bool Prev() override; void Seek(S2CellId target) override; bool Locate(const S2Point& target) override { return LocateImpl(*this, target); } S2CellRelation Locate(S2CellId target) override { return LocateImpl(*this, target); } std::unique_ptr Clone() const override { return std::make_unique(*this); } private: const MutableS2ShapeIndex* index_ = nullptr; CellMap::const_iterator iter_, end_; }; // Takes ownership of the given shape and adds it to the index. Assigns a // unique id to the shape for this index and returns it. Shape ids are // assigned sequentially starting from 0 in the order shapes are added. // Invalidates all iterators and their associated data. // // Note that this method is not affected by S2MemoryTracker, i.e. shapes can // continue to be added even once the specified limit has been reached. int Add(std::unique_ptr shape); // Removes the given shape from the index. Invalidates all iterators and // their associated data. To retain ownership of the shape, use Release() // instead. // // Note that SpaceUsed() does not consider the size of removed shapes, causing // it to undercount the memory used by removed shapes. This memory is released // when the index is next built. void Remove(int shape_id); // Removes the given shape from the index and return ownership to the caller. // Invalidates all iterators and their associated data. To simply remove the // shape and destroy it, use Remove() instead. std::unique_ptr Release(int shape_id); // Resets the index to its original state and returns ownership of all // shapes to the caller. This method is much more efficient than removing // all shapes one at a time. std::vector> ReleaseAll(); // Resets the index to its original state and deletes all shapes. Any // options specified via Init() are preserved. void Clear(); // Returns the number of bytes currently occupied by the index (including any // unused space at the end of vectors, etc). It has the same thread safety // as the other "const" methods (see introduction). size_t SpaceUsed() const override; // Calls to Add() and Release() are normally queued and processed on the // first subsequent query (in a thread-safe way). Building the index lazily // in this way has several advantages, the most important of which is that // sometimes there *is* no subsequent query and the index doesn't need to be // built at all. // // In contrast, ForceBuild() causes any pending updates to be applied // immediately. It is thread-safe and may be called simultaneously with // other "const" methods (see notes on thread safety above). Similarly this // method is "const" since it does not modify the visible index contents. // // ForceBuild() should not normally be called since it prevents lazy index // construction (which is usually beneficial). Some reasons to use it // include: // // - To exclude the cost of building the index from benchmark results. // - To ensure that the first subsequent query is as fast as possible. // - To ensure that the index can be built successfully without exceeding a // specified S2MemoryTracker limit (see the constructor for details). // // Note that this method is thread-safe. void ForceBuild() const; // Returns true if there are no pending updates that need to be applied. // This can be useful to avoid building the index unnecessarily, or for // choosing between two different algorithms depending on whether the index // is available. // // The returned index status may be slightly out of date if the index was // built in a different thread. This is fine for the intended use (as an // efficiency hint), but it should not be used by internal methods (see // MaybeApplyUpdates). bool is_fresh() const; protected: std::unique_ptr NewIterator(InitialPosition pos) const override; private: friend class EncodedS2ShapeIndex; friend class Iterator; friend class MutableS2ShapeIndexTest; friend class S2Stats; class BatchGenerator; class EdgeAllocator; class InteriorTracker; struct BatchDescriptor; struct ClippedEdge; struct FaceEdge; struct PendingRemoval; using ShapeEdgeId = s2shapeutil::ShapeEdgeId; using ShapeIdSet = std::vector; // When adding a new encoding, be aware that old binaries will not be able // to decode it. static constexpr unsigned char kCurrentEncodingVersionNumber = 0; // Internal methods are documented with their definitions. bool is_shape_being_removed(int shape_id) const; bool MaybeCreatePendingRemovals(); void MarkIndexStale(); void MaybeApplyUpdates() const; void ApplyUpdatesThreadSafe(); void ApplyUpdatesInternal(); std::vector GetUpdateBatches() const; void ReserveSpace(const BatchDescriptor& batch, std::vector all_edges[6]); void AddShape(const S2Shape* shape, int shape_id, int edges_begin, int edges_end, std::vector all_edges[6], InteriorTracker* tracker) const; void RemoveShape(const S2Shape* shape, int shape_id, std::vector all_edges[6], InteriorTracker* tracker) const; void FinishPartialShape(int shape_id); void AddFaceEdge(FaceEdge* edge, std::vector all_edges[6]) const; void UpdateFaceEdges(int face, absl::Span face_edges, InteriorTracker* tracker); S2CellId ShrinkToFit(const S2PaddedCell& pcell, const R2Rect& bound) const; void SkipCellRange(S2CellId begin, S2CellId end, InteriorTracker* tracker, EdgeAllocator* alloc, bool disjoint_from_index); void UpdateEdges(const S2PaddedCell& pcell, std::vector* edges, InteriorTracker* tracker, EdgeAllocator* alloc, bool disjoint_from_index); void AbsorbIndexCell(const S2PaddedCell& pcell, const Iterator& iter, std::vector* edges, InteriorTracker* tracker, EdgeAllocator* alloc); int GetEdgeMaxLevel(const S2Shape::Edge& edge) const; static int CountShapes(const std::vector& edges, const ShapeIdSet& cshape_ids); bool MakeIndexCell(const S2PaddedCell& pcell, const std::vector& edges, InteriorTracker* tracker); static void TestAllEdges(const std::vector& edges, InteriorTracker* tracker); inline static const ClippedEdge* UpdateBound(const ClippedEdge* edge, int u_end, double u, int v_end, double v, EdgeAllocator* alloc); static const ClippedEdge* ClipUBound(const ClippedEdge* edge, int u_end, double u, EdgeAllocator* alloc); static const ClippedEdge* ClipVBound(const ClippedEdge* edge, int v_end, double v, EdgeAllocator* alloc); static void ClipVAxis(const ClippedEdge* edge, const R1Interval& middle, std::vector child_edges[2], EdgeAllocator* alloc); // The shapes in the index, accessed by their shape id. Removed shapes are // replaced by nullptr pointers. std::vector> shapes_; // A map from S2CellId to the set of clipped shapes that intersect that // cell. The cell ids cover a set of non-overlapping regions on the // sphere. Note that this field is updated lazily (see below). Const // methods *must* call MaybeApplyUpdates() before accessing this field. // (The easiest way to achieve this is simply to use an Iterator.) CellMap cell_map_; // The options supplied for this index. Options options_; // The id of the first shape that has been queued for addition but not // processed yet. int pending_additions_begin_ = 0; // The set of shapes that have been queued for removal but not processed // yet. Shapes are moved here from the main shapes_ vector when Release() // is called (Remove just moves the original shape). This field is present // only when there are removed shapes to process (to save memory). std::unique_ptr> pending_removals_; // Additions and removals are queued and processed on the first subsequent // query. There are several reasons to do this: // // - It is significantly more efficient to process updates in batches. // - Often the index will never be queried, in which case we can save both // the time and memory required to build it. Examples: // + S2Loops that are created simply to pass to an S2Polygon. (We don't // need the S2Loop index, because S2Polygon builds its own index.) // + Applications that load a database of geometry and then query only // a small fraction of it. // + Applications that only read and write geometry (Decode/Encode). // // The main drawback is that we need to go to some extra work to ensure that // "const" methods are still thread-safe. Note that the goal is *not* to // make this class thread-safe in general, but simply to hide the fact that // we defer some of the indexing work until query time. // // The textbook approach to this problem would be to use a mutex and a // condition variable. Unfortunately pthread mutexes are huge (40 bytes). // Instead we use spinlock (which is only 4 bytes) to guard a few small // fields representing the current update status, and only create additional // state while the update is actually occurring. mutable SpinLock lock_; enum IndexStatus { STALE, // There are pending updates. UPDATING, // Updates are currently being applied. FRESH, // There are no pending updates. }; // Reads and writes to this field are guarded by "lock_". std::atomic index_status_{FRESH}; // UpdateState holds temporary data related to thread synchronization. It // is only allocated while updates are being applied. struct UpdateState { // This mutex is used as a condition variable. It is locked by the // updating thread for the entire duration of the update; other threads // lock it in order to wait until the update is finished. absl::Mutex wait_mutex; // The number of threads currently waiting on "wait_mutex_". The // UpdateState can only be freed when this number reaches zero. // // Reads and writes to this field are guarded by "lock_". int num_waiting = 0; ~UpdateState() { ABSL_DCHECK_EQ(0, num_waiting); } }; std::unique_ptr update_state_; S2MemoryTracker::Client mem_tracker_; #ifndef SWIG // Documented in the .cc file. void UnlockAndSignal() ABSL_UNLOCK_FUNCTION(lock_) ABSL_UNLOCK_FUNCTION(update_state_->wait_mutex); #endif MutableS2ShapeIndex(const MutableS2ShapeIndex&) = delete; MutableS2ShapeIndex& operator=(const MutableS2ShapeIndex&) = delete; }; // The following flag can be used to limit the amount of temporary memory used // when building an S2ShapeIndex. See the .cc file for details. // // DEFAULT: 100 MB ABSL_DECLARE_FLAG(int64_t, s2shape_index_tmp_memory_budget); ////////////////// Implementation details follow //////////////////// // A BatchDescriptor represents a set of pending updates that will be applied // at the same time. The batch consists of all edges in (shape id, edge id) // order from "begin" (inclusive) to "end" (exclusive). Note that the last // shape in a batch may have only some of its edges added. The first batch // also implicitly includes all shapes being removed. "num_edges" is the // total number of edges that will be added or removed in this batch. struct MutableS2ShapeIndex::BatchDescriptor { // REQUIRES: If end.edge_id != 0, it must refer to a valid edge. ShapeEdgeId begin, end; int num_edges; }; // A shape that has been queued for removal. struct MutableS2ShapeIndex::PendingRemoval { int shape_id; std::unique_ptr shape; }; // The purpose of BatchGenerator is to divide large updates into batches such // that all batches use approximately the same amount of high-water memory. // This class is defined here so that it can be tested independently. class MutableS2ShapeIndex::BatchGenerator { public: // Given the total number of edges that will be removed and added, prepares // to divide the edges into batches. "shape_id_begin" identifies the first // shape whose edges will be added. BatchGenerator(int64_t num_edges_removed, int64_t num_edges_added, int shape_id_begin); // Indicates that the given shape will be added to the index. Shapes with // few edges will be grouped together into a single batch, while shapes with // many edges will be split over several batches if necessary. void AddShape(int shape_id, int num_edges); // Returns a vector describing each batch. This method should be called // once all shapes have been added. std::vector Finish(); private: // Returns a vector indicating the maximum number of edges in each batch. // (The actual batch sizes are adjusted later in order to avoid splitting // shapes between batches unnecessarily.) static std::vector GetMaxBatchSizes(int64_t num_edges_removed, int64_t num_edges_added); // Returns the maximum number of edges in the current batch. int max_batch_size() const { return max_batch_sizes_[batch_index_]; } // Returns the maximum number of edges in the next batch. int next_max_batch_size() const { return max_batch_sizes_[batch_index_ + 1]; } // Adds the given number of edges to the current batch. void ExtendBatch(int num_edges) { batch_size_ += num_edges; } // Adds the given number of edges to the current batch, ending with the edge // just before "batch_end", and then starts a new batch. void FinishBatch(int num_edges, ShapeEdgeId batch_end); // A vector representing the ideal number of edges in each batch; the batch // sizes gradually decrease to ensure that each batch uses approximately the // same total amount of memory as the index grows. The actual batch sizes // are then adjusted based on how many edges each shape has in order to // avoid splitting shapes between batches unnecessarily. std::vector max_batch_sizes_; // The maximum size of the current batch is determined by how many edges // have been added to the index so far. For example if GetBatchSizes() // returned {100, 70, 50, 30} and we have added 0 edges, the current batch // size is 100. But if we have already added 90 edges then the current // batch size would be 70, and if have added 150 edges the batch size would // be 50. We keep track of (1) the current index into batch_sizes and (2) // the number of edges remaining before we increment the batch index. int batch_index_ = 0; int batch_index_edges_left_ = 0; ShapeEdgeId batch_begin_; // The start of the current batch. int shape_id_end_; // One beyond the last shape to be added. int batch_size_ = 0; // The number of edges in the current batch. std::vector batches_; // The completed batches so far. }; inline MutableS2ShapeIndex::Iterator::Iterator( const MutableS2ShapeIndex* index, InitialPosition pos) { Init(index, pos); } inline void MutableS2ShapeIndex::Iterator::Init( const MutableS2ShapeIndex* index, InitialPosition pos) { index->MaybeApplyUpdates(); InitStale(index, pos); } inline void MutableS2ShapeIndex::Iterator::InitStale( const MutableS2ShapeIndex* index, InitialPosition pos) { index_ = index; end_ = index_->cell_map_.end(); iter_ = end_; if (pos == BEGIN) { iter_ = index_->cell_map_.begin(); } } inline void MutableS2ShapeIndex::Iterator::Begin() { // Make sure that the index has not been modified since Init() was called. ABSL_DCHECK(index_->is_fresh()); iter_ = index_->cell_map_.begin(); } inline void MutableS2ShapeIndex::Iterator::Finish() { iter_ = end_; } inline void MutableS2ShapeIndex::Iterator::Next() { ABSL_DCHECK(!done()); ++iter_; } inline bool MutableS2ShapeIndex::Iterator::Prev() { if (iter_ == index_->cell_map_.begin()) { return false; } --iter_; return true; } inline void MutableS2ShapeIndex::Iterator::Seek(S2CellId target) { iter_ = index_->cell_map_.lower_bound(target); } inline std::unique_ptr MutableS2ShapeIndex::NewIterator(InitialPosition pos) const { return std::make_unique(this, pos); } inline void MutableS2ShapeIndex::ForceBuild() const { MaybeApplyUpdates(); } inline bool MutableS2ShapeIndex::is_fresh() const { return index_status_.load(std::memory_order_relaxed) == FRESH; } // Given that the given shape is being updated, return true if it is being // removed (as opposed to being added). inline bool MutableS2ShapeIndex::is_shape_being_removed(int shape_id) const { // All shape ids being removed are less than all shape ids being added. return shape_id < pending_additions_begin_; } // Ensure that any pending updates have been applied. This method must be // called before accessing the cell_map_ field, even if the index_status_ // appears to be FRESH, because a memory barrier is required in order to // ensure that all the index updates are visible if the updates were done in // another thread. inline void MutableS2ShapeIndex::MaybeApplyUpdates() const { // To avoid acquiring and releasing the spinlock on every query, we use // atomic operations when testing whether the status is FRESH and when // updating the status to be FRESH. This guarantees that any thread that // sees a status of FRESH will also see the corresponding index updates. if (index_status_.load(std::memory_order_acquire) != FRESH) { const_cast(this)->ApplyUpdatesThreadSafe(); } } #endif // S2_MUTABLE_S2SHAPE_INDEX_H_ src/s2/mutable_s2shape_index_test.cc000066400000000000000000001126551524103652300200170ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/mutable_s2shape_index.h" #include #include #include #include #include #include #include #include #include #include #include #include #include #include "absl/flags/declare.h" #include "absl/flags/flag.h" #include "absl/flags/reflection.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "absl/strings/str_cat.h" #include "absl/strings/str_format.h" #include "absl/types/span.h" #include "s2/base/log_severity.h" #include "s2/r2.h" #include "s2/r2rect.h" #include "s2/s1angle.h" #include "s2/s2cell.h" #include "s2/s2cell_id.h" #include "s2/s2cell_union.h" #include "s2/s2coords.h" #include "s2/s2edge_clipping.h" #include "s2/s2edge_distances.h" #include "s2/s2edge_vector_shape.h" #include "s2/s2error.h" #include "s2/s2fractal.h" #include "s2/s2lax_polygon_shape.h" #include "s2/s2lax_polyline_shape.h" #include "s2/s2loop.h" #include "s2/s2memory_tracker.h" #include "s2/s2padded_cell.h" #include "s2/s2point.h" #include "s2/s2point_vector_shape.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2random.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2shapeutil_coding.h" #include "s2/s2shapeutil_contains_brute_force.h" #include "s2/s2shapeutil_testing.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" #include "s2/thread_testing.h" #include "s2/util/coding/coder.h" #include "s2/util/math/matrix3x3.h" #include "s2/util/random/shared_bit_gen.h" using absl::WrapUnique; using s2textformat::MakePolylineOrDie; using std::make_unique; using std::string; using std::unique_ptr; using std::vector; ABSL_DECLARE_FLAG(double, s2shape_index_min_short_edge_fraction); class MutableS2ShapeIndexTest : public ::testing::Test { protected: // This test harness owns a MutableS2ShapeIndex for convenience. MutableS2ShapeIndex index_; // Verifies that that every cell of the index contains the correct edges, and // that no cells are missing from the index. The running time of this // function is quadratic in the number of edges. void QuadraticValidate(); // Given an edge and a cell id, determines whether or not the edge should be // present in that cell and verify that this matches "index_has_edge". void ValidateEdge(const S2Point& a, const S2Point& b, S2CellId id, bool index_has_edge); // Given a shape and a cell id, determines whether or not the shape contains // the cell center and verify that this matches "index_contains_center". void ValidateInterior(const S2Shape* shape, S2CellId id, bool index_contains_center); // Verifies that the index can be encoded and decoded without change. void TestEncodeDecode(); using BatchDescriptor = MutableS2ShapeIndex::BatchDescriptor; // Converts the given vector of batches to a human-readable form. static string ToString(absl::Span batches); // Verifies that removing and adding the given combination of shapes with // the given memory budget yields the expected vector of batches. void TestBatchGenerator(int num_edges_removed, absl::Span shape_edges_added, int64_t tmp_memory_budget, int shape_id_begin, absl::Span expected_batches); }; void MutableS2ShapeIndexTest::QuadraticValidate() { // Iterate through a sequence of nonoverlapping cell ids that cover the // sphere and include as a subset all the cell ids used in the index. For // each cell id, verify that the expected set of edges is present. // "min_cellid" is the first S2CellId that has not been validated yet. S2CellId min_cellid = S2CellId::Begin(S2CellId::kMaxLevel); for (MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); ; it.Next()) { // Generate a list of S2CellIds ("skipped cells") that cover the gap // between the last cell we validated and the next cell in the index. S2CellUnion skipped; if (!it.done()) { S2CellId cellid = it.id(); EXPECT_GE(cellid, min_cellid); skipped.InitFromBeginEnd(min_cellid, cellid.range_min()); min_cellid = cellid.range_max().next(); } else { // Validate the empty cells beyond the last cell in the index. skipped.InitFromBeginEnd(min_cellid, S2CellId::End(S2CellId::kMaxLevel)); } // Iterate through all the shapes, simultaneously validating the current // index cell and all the skipped cells. int num_edges = 0; // all edges in the cell int num_short_edges = 0; // "short" edges int num_containing_shapes = 0; // shapes containing cell's entry vertex for (int id = 0; id < index_.num_shape_ids(); ++id) { const S2Shape* shape = index_.shape(id); const S2ClippedShape* clipped = nullptr; if (!it.done()) clipped = it.cell().find_clipped(id); // First check that contains_center() is set correctly. for (S2CellId skipped_id : skipped) { ValidateInterior(shape, skipped_id, false); } if (!it.done()) { bool contains_center = clipped && clipped->contains_center(); ValidateInterior(shape, it.id(), contains_center); S2PaddedCell pcell(it.id(), MutableS2ShapeIndex::kCellPadding); if (shape != nullptr) { num_containing_shapes += s2shapeutil::ContainsBruteForce(*shape, pcell.GetEntryVertex()); } } // If this shape has been released, it should not be present at all. if (shape == nullptr) { EXPECT_EQ(nullptr, clipped); continue; } // Otherwise check that the appropriate edges are present. for (int e = 0; e < shape->num_edges(); ++e) { auto edge = shape->edge(e); for (int j = 0; j < skipped.num_cells(); ++j) { ValidateEdge(edge.v0, edge.v1, skipped.cell_id(j), false); } if (!it.done()) { bool has_edge = clipped && clipped->ContainsEdge(e); ValidateEdge(edge.v0, edge.v1, it.id(), has_edge); int max_level = index_.GetEdgeMaxLevel(edge); if (has_edge) { ++num_edges; if (it.id().level() < max_level) ++num_short_edges; } } } } // This mirrors the calculation in MutableS2ShapeIndex::MakeIndexCell(). // It is designed to ensure that the index size is always linear in the // number of indexed edges. int max_short_edges = std::max( index_.options().max_edges_per_cell(), static_cast( absl::GetFlag(FLAGS_s2shape_index_min_short_edge_fraction) * (num_edges + num_containing_shapes))); EXPECT_LE(num_short_edges, max_short_edges); if (it.done()) break; } } // Verify that "index_has_edge" is true if and only if the edge AB intersects // the given cell id. void MutableS2ShapeIndexTest::ValidateEdge(const S2Point& a, const S2Point& b, S2CellId id, bool index_has_edge) { // Expand or shrink the padding slightly to account for errors in the // function we use to test for intersection (IntersectsRect). double padding = MutableS2ShapeIndex::kCellPadding; padding += (index_has_edge ? 1 : -1) * S2::kIntersectsRectErrorUVDist; R2Rect bound = id.GetBoundUV().Expanded(padding); R2Point a_uv, b_uv; EXPECT_EQ(S2::ClipToPaddedFace(a, b, id.face(), padding, &a_uv, &b_uv) && S2::IntersectsRect(a_uv, b_uv, bound), index_has_edge); } void MutableS2ShapeIndexTest::ValidateInterior( const S2Shape* shape, S2CellId id, bool index_contains_center) { if (shape == nullptr) { EXPECT_FALSE(index_contains_center); } else { EXPECT_EQ(s2shapeutil::ContainsBruteForce(*shape, id.ToPoint()), index_contains_center); } } void MutableS2ShapeIndexTest::TestEncodeDecode() { Encoder encoder; index_.Encode(&encoder); Decoder decoder(encoder.base(), encoder.length()); MutableS2ShapeIndex index2; ASSERT_TRUE(index2.Init(&decoder, s2shapeutil::WrappedShapeFactory(&index_))); s2testing::ExpectEqual(index_, index2); } /*static*/ string MutableS2ShapeIndexTest::ToString( absl::Span batches) { string result; for (const auto& batch : batches) { if (!result.empty()) result += ", "; absl::StrAppendFormat(&result, "(%d:%d, %d:%d, %d)", batch.begin.shape_id, batch.begin.edge_id, batch.end.shape_id, batch.end.edge_id, batch.num_edges); } return result; } void MutableS2ShapeIndexTest::TestBatchGenerator( int num_edges_removed, absl::Span shape_edges_added, int64_t tmp_memory_budget, int shape_id_begin, absl::Span expected_batches) { absl::FlagSaver fs; absl::SetFlag(&FLAGS_s2shape_index_tmp_memory_budget, tmp_memory_budget); int num_edges_added = 0; for (auto n : shape_edges_added) num_edges_added += n; MutableS2ShapeIndex::BatchGenerator bgen(num_edges_removed, num_edges_added, shape_id_begin); for (int i = 0; i < shape_edges_added.size(); ++i) { bgen.AddShape(shape_id_begin + i, shape_edges_added[i]); } auto actual_batches = bgen.Finish(); EXPECT_EQ(ToString(actual_batches), ToString(expected_batches)); } namespace { void TestIteratorMethods(const MutableS2ShapeIndex& index) { MutableS2ShapeIndex::Iterator it(&index, S2ShapeIndex::BEGIN); EXPECT_FALSE(it.Prev()); it.Finish(); EXPECT_TRUE(it.done()); vector ids; MutableS2ShapeIndex::Iterator it2(&index); S2CellId min_cellid = S2CellId::Begin(S2CellId::kMaxLevel); for (it.Begin(); !it.done(); it.Next()) { S2CellId cellid = it.id(); auto skipped = S2CellUnion::FromBeginEnd(min_cellid, cellid.range_min()); for (S2CellId skipped_id : skipped) { EXPECT_FALSE(it2.Locate(skipped_id.ToPoint())); EXPECT_EQ(S2CellRelation::DISJOINT, it2.Locate(skipped_id)); it2.Begin(); it2.Seek(skipped_id); EXPECT_EQ(cellid, it2.id()); } if (!ids.empty()) { it2 = it; EXPECT_TRUE(it2.Prev()); EXPECT_EQ(ids.back(), it2.id()); it2.Next(); EXPECT_EQ(cellid, it2.id()); it2.Seek(ids.back()); EXPECT_EQ(ids.back(), it2.id()); } it2.Begin(); EXPECT_EQ(cellid.ToPoint(), it.id().ToPoint()); EXPECT_TRUE(it2.Locate(it.id().ToPoint())); EXPECT_EQ(cellid, it2.id()); it2.Begin(); EXPECT_EQ(S2CellRelation::INDEXED, it2.Locate(cellid)); EXPECT_EQ(cellid, it2.id()); if (!cellid.is_face()) { it2.Begin(); EXPECT_EQ(S2CellRelation::SUBDIVIDED, it2.Locate(cellid.parent())); EXPECT_LE(it2.id(), cellid); EXPECT_GE(it2.id(), cellid.parent().range_min()); } if (!cellid.is_leaf()) { for (int i = 0; i < 4; ++i) { it2.Begin(); EXPECT_EQ(S2CellRelation::INDEXED, it2.Locate(cellid.child(i))); EXPECT_EQ(cellid, it2.id()); } } ids.push_back(cellid); min_cellid = cellid.range_max().next(); } } // NOTE(ericv): The tests below are all somewhat fragile since they depend on // the internal BatchGenerator heuristics; if these heuristics change // (including constants) then the tests below may need to change as well. TEST_F(MutableS2ShapeIndexTest, RemoveFullPolygonBatch) { TestBatchGenerator(0, {}, 100 /*bytes*/, 7, {{{7, 0}, {7, 0}, 0}}); } TEST_F(MutableS2ShapeIndexTest, AddFullPolygonBatch) { TestBatchGenerator(0, {0}, 100 /*bytes*/, 7, {{{7, 0}, {8, 0}, 0}}); } TEST_F(MutableS2ShapeIndexTest, RemoveManyEdgesInOneBatch) { // Test removing more edges than would normally fit in a batch. For good // measure we also add two full polygons in the same batch. TestBatchGenerator(1000, {0, 0}, 100 /*bytes*/, 7, {{{7, 0}, {9, 0}, 1000}}); } TEST_F(MutableS2ShapeIndexTest, RemoveAndAddEdgesInOneBatch) { // Test removing and adding edges in one batch. TestBatchGenerator(3, {4, 5}, 10000 /*bytes*/, 7, {{{7, 0}, {9, 0}, 12}}); } TEST_F(MutableS2ShapeIndexTest, RemoveAndAddEdgesInTwoBatches) { // Test removing many edges and then adding a few. TestBatchGenerator(1000, {3}, 1000 /*bytes*/, 7, {{{7, 0}, {7, 0}, 1000}, {{7, 0}, {8, 0}, 3}}); } TEST_F(MutableS2ShapeIndexTest, RemoveAndAddEdgesAndFullPolygonsInTwoBatches) { // Like the above, but also add two full polygons such that one polygon is // processed in each batch. TestBatchGenerator(1000, {0, 3, 0}, 1000 /*bytes*/, 7, {{{7, 0}, {8, 0}, 1000}, {{8, 0}, {10, 0}, 3}}); } TEST_F(MutableS2ShapeIndexTest, SeveralShapesInOneBatch) { // Test adding several shapes in one batch. TestBatchGenerator(0, {3, 4, 5}, 10000 /*bytes*/, 7, {{{7, 0}, {10, 0}, 12}}); } TEST_F(MutableS2ShapeIndexTest, GroupSmallShapesIntoBatches) { // Test adding several small shapes that must be split into batches. // 10000 bytes ~= temporary space to process 48 edges. TestBatchGenerator(0, {20, 20, 20, 20, 20}, 10000 /*bytes*/, 7, {{{7, 0}, {9, 0}, 40}, {{9, 0}, {11, 0}, 40}, {{11, 0}, {12, 0}, 20}}); } TEST_F(MutableS2ShapeIndexTest, AvoidPartialShapeInBatch) { // Test adding a small shape followed by a large shape that won't fit in the // same batch as the small shape, but will fit in its own separate batch. // 10000 bytes ~= temporary space to process 48 edges. TestBatchGenerator(0, {20, 40, 20}, 10000 /*bytes*/, 7, {{{7, 0}, {8, 0}, 20}, {{8, 0}, {9, 0}, 40}, {{9, 0}, {10, 0}, 20}}); } TEST_F(MutableS2ShapeIndexTest, SplitShapeIntoTwoBatches) { // Test adding a few small shapes, then a large shape that can be split // across the remainder of the first batch plus the next batch. The first // two batches should have the same amount of remaining space relative to // their maximum size. (For 10000 bytes of temporary space, the ideal batch // sizes are 48, 46, 45.) // // Note that we need a separate batch for the full polygon at the end, even // though it has no edges, because partial shapes must always be the last // shape in their batch. TestBatchGenerator(0, {20, 60, 0}, 10000 /*bytes*/, 7, {{{7, 0}, {8, 21}, 41}, {{8, 21}, {9, 0}, 39}, {{9, 0}, {10, 0}, 0}}); } TEST_F(MutableS2ShapeIndexTest, RemoveEdgesAndAddPartialShapeInSameBatch) { // Test a batch that consists of removing some edges and then adding a // partial shape. We also check that the small shape at the end is put into // its own batch, since partial shapes must be the last shape in their batch. TestBatchGenerator(20, {60, 5}, 10000 /*bytes*/, 7, {{{7, 0}, {7, 21}, 41}, {{7, 21}, {8, 0}, 39}, {{8, 0}, {9, 0}, 5}}); } TEST_F(MutableS2ShapeIndexTest, SplitShapeIntoManyBatches) { // Like the above except that the shape is split into 10 batches. With // 10000 bytes of temporary space, the ideal batch sizes are 63, 61, 59, 57, // 55, 53, 51, 49, 48, 46. The first 8 batches are as full as possible, // while the last two batches have the same amount of remaining space // relative to their ideal size. There is also a small batch at the end. TestBatchGenerator(0, {20, 500, 5}, 10000 /*bytes*/, 7, {{{7, 0}, {8, 43}, 63}, {{8, 43}, {8, 104}, 61}, {{8, 104}, {8, 163}, 59}, {{8, 163}, {8, 220}, 57}, {{8, 220}, {8, 275}, 55}, {{8, 275}, {8, 328}, 53}, {{8, 328}, {8, 379}, 51}, {{8, 379}, {8, 428}, 49}, {{8, 428}, {8, 465}, 37}, {{8, 465}, {9, 0}, 35}, {{9, 0}, {10, 0}, 5}}); } TEST_F(MutableS2ShapeIndexTest, SpaceUsed) { index_.Add(make_unique(S2Point(1, 0, 0), S2Point(0, 1, 0))); EXPECT_FALSE(index_.is_fresh()); size_t size_before = index_.SpaceUsed(); EXPECT_FALSE(index_.is_fresh()); QuadraticValidate(); size_t size_after = index_.SpaceUsed(); EXPECT_TRUE(index_.is_fresh()); EXPECT_TRUE(size_after > size_before); } TEST_F(MutableS2ShapeIndexTest, NoEdges) { MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); EXPECT_TRUE(it.done()); TestIteratorMethods(index_); TestEncodeDecode(); } TEST_F(MutableS2ShapeIndexTest, OneEdge) { EXPECT_EQ(0, index_.Add(make_unique(S2Point(1, 0, 0), S2Point(0, 1, 0)))); QuadraticValidate(); TestIteratorMethods(index_); TestEncodeDecode(); } TEST_F(MutableS2ShapeIndexTest, ShrinkToFitOptimization) { // This used to trigger a bug in the ShrinkToFit optimization. The loop // below contains almost all of face 0 except for a small region in the // 0/00000 subcell. That subcell is the only one that contains any edges. // This caused the index to be built only in that subcell. However, all the // other cells on that face should also have index entries, in order to // indicate that they are contained by the loop. unique_ptr loop(S2Loop::MakeRegularLoop( S2Point(1, 0.5, 0.5).Normalize(), S1Angle::Degrees(89), 100)); index_.Add(make_unique(loop.get())); QuadraticValidate(); TestEncodeDecode(); } TEST_F(MutableS2ShapeIndexTest, LoopsSpanningThreeFaces) { S2Polygon polygon; constexpr int kNumEdges = 100; // Validation is quadratic // Construct two loops consisting of kNumEdges vertices each, centered // around the cube vertex at the start of the Hilbert curve. S2Testing::ConcentricLoopsPolygon(S2Point(1, -1, -1).Normalize(), 2, kNumEdges, &polygon); vector> loops = polygon.Release(); for (auto& loop : loops) { index_.Add(make_unique(&*loop)); } QuadraticValidate(); TestIteratorMethods(index_); TestEncodeDecode(); } TEST_F(MutableS2ShapeIndexTest, ManyIdenticalEdges) { constexpr int kNumEdges = 100; // Validation is quadratic S2Point a = S2Point(0.99, 0.99, 1).Normalize(); S2Point b = S2Point(-0.99, -0.99, 1).Normalize(); for (int i = 0; i < kNumEdges; ++i) { EXPECT_EQ(i, index_.Add(make_unique(a, b))); } QuadraticValidate(); TestIteratorMethods(index_); TestEncodeDecode(); // Since all edges span the diagonal of a face, no subdivision should // have occurred (with the default index options). for (MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { EXPECT_EQ(0, it.id().level()); } } TEST_F(MutableS2ShapeIndexTest, DegenerateEdge) { // This test verifies that degenerate edges are supported. The following // point is a cube face vertex, and so it should be indexed in 3 cells. S2Point a = S2Point(1, 1, 1).Normalize(); auto shape = make_unique(); shape->Add(a, a); index_.Add(std::move(shape)); QuadraticValidate(); TestEncodeDecode(); // Check that exactly 3 index cells contain the degenerate edge. int count = 0; for (MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); !it.done(); it.Next(), ++count) { EXPECT_TRUE(it.id().is_leaf()); EXPECT_EQ(1, it.cell().num_clipped()); EXPECT_EQ(1, it.cell().clipped(0).num_edges()); } EXPECT_EQ(3, count); } TEST_F(MutableS2ShapeIndexTest, ManyTinyEdges) { // This test adds many edges to a single leaf cell, to check that // subdivision stops when no further subdivision is possible. constexpr int kNumEdges = 100; // Validation is quadratic // Construct two points in the same leaf cell. S2Point a = S2CellId(S2Point(1, 0, 0)).ToPoint(); S2Point b = (a + S2Point(0, 1e-12, 0)).Normalize(); auto shape = make_unique(); for (int i = 0; i < kNumEdges; ++i) { shape->Add(a, b); } index_.Add(std::move(shape)); QuadraticValidate(); TestEncodeDecode(); // Check that there is exactly one index cell and that it is a leaf cell. MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); ASSERT_TRUE(!it.done()); EXPECT_TRUE(it.id().is_leaf()); it.Next(); EXPECT_TRUE(it.done()); } TEST_F(MutableS2ShapeIndexTest, SimpleUpdates) { // Add 5 loops one at a time, then release them one at a time, // validating the index at each step. S2Polygon polygon; S2Testing::ConcentricLoopsPolygon(S2Point(1, 0, 0), 5, 20, &polygon); for (int i = 0; i < polygon.num_loops(); ++i) { index_.Add(make_unique(polygon.loop(i))); QuadraticValidate(); } for (int id = 0; id < polygon.num_loops(); ++id) { index_.Release(id); EXPECT_EQ(index_.shape(id), nullptr); QuadraticValidate(); TestEncodeDecode(); } } TEST_F(MutableS2ShapeIndexTest, RandomUpdates) { // Set the temporary memory budget such that at least one shape needs to be // split into multiple update batches (namely, the "5 concentric rings" // polygon below which needs ~25KB of temporary space). absl::FlagSaver fs; absl::SetFlag(&FLAGS_s2shape_index_tmp_memory_budget, 10000); // Allow the seed to be varied from the command line. absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "RANDOM_UPDATES", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); // A few polylines. index_.Add(make_unique( MakePolylineOrDie("0:0, 2:1, 0:2, 2:3, 0:4, 2:5, 0:6"))); index_.Add(make_unique( MakePolylineOrDie("1:0, 3:1, 1:2, 3:3, 1:4, 3:5, 1:6"))); index_.Add(make_unique( MakePolylineOrDie("2:0, 4:1, 2:2, 4:3, 2:4, 4:5, 2:6"))); // A loop that used to trigger an indexing bug. index_.Add(make_unique(S2Loop::MakeRegularLoop( S2Point(1, 0.5, 0.5).Normalize(), S1Angle::Degrees(89), 20))); // Five concentric loops. S2Polygon polygon5; S2Testing::ConcentricLoopsPolygon(S2Point(1, -1, -1).Normalize(), 5, 20, &polygon5); for (int i = 0; i < polygon5.num_loops(); ++i) { index_.Add(make_unique(polygon5.loop(i))); } // Two clockwise loops around S2Cell cube vertices. index_.Add(make_unique(S2Loop::MakeRegularLoop( S2Point(-1, 1, 1).Normalize(), S1Angle::Radians(M_PI - 0.001), 10))); index_.Add(make_unique(S2Loop::MakeRegularLoop( S2Point(-1, -1, -1).Normalize(), S1Angle::Radians(M_PI - 0.001), 10))); // A shape with no edges and no interior. index_.Add(make_unique( make_unique(S2Loop::kEmpty()))); // A shape with no edges that covers the entire sphere. index_.Add(make_unique( make_unique(S2Loop::kFull()))); vector> released; vector added(index_.num_shape_ids()); std::iota(added.begin(), added.end(), 0); QuadraticValidate(); TestEncodeDecode(); for (int iter = 0; iter < 100; ++iter) { ABSL_VLOG(1) << "Iteration: " << iter; // Choose some shapes to add and release. int num_updates = 1 + s2random::SkewedInt(bitgen, 5); for (int n = 0; n < num_updates; ++n) { if (absl::Bernoulli(bitgen, 0.5) && !added.empty()) { size_t i = absl::Uniform(bitgen, 0, added.size()); ABSL_VLOG(1) << " Released shape " << added[i] << " (" << index_.shape(added[i]) << ")"; released.push_back(index_.Release(added[i])); added.erase(added.begin() + i); } else if (!released.empty()) { size_t i = absl::Uniform(bitgen, 0, released.size()); S2Shape* shape = released[i].get(); int shape_id = index_.Add(std::move(released[i])); released.erase(released.begin() + i); added.push_back(shape_id); ABSL_VLOG(1) << " Added shape " << shape_id << " (" << shape << ")"; } } QuadraticValidate(); TestEncodeDecode(); } } // A test that repeatedly updates "index_" in one thread and attempts to // concurrently read the index_ from several other threads. When all threads // have finished reading, the first thread makes another update. // // Note that we only test concurrent read access, since MutableS2ShapeIndex // requires all updates to be single-threaded and not concurrent with any // reads. class LazyUpdatesTest : public s2testing::ReaderWriterTest { public: LazyUpdatesTest() = default; void WriteOp() override { util_random::SharedBitGen bitgen; index_.Clear(); int num_vertices = 4 * s2random::SkewedInt(bitgen, 10); // Up to 4K vertices unique_ptr loop(S2Loop::MakeRegularLoop( s2random::Point(bitgen), S2Testing::KmToAngle(5), num_vertices)); index_.Add(make_unique(std::move(loop))); } void ReadOp() override { for (MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { continue; // NOLINT } } protected: MutableS2ShapeIndex index_; }; TEST(MutableS2ShapeIndex, ConstMethodsThreadSafe) { // Ensure that lazy updates are thread-safe. In other words, make sure that // nothing bad happens when multiple threads call "const" methods that // cause pending updates to be applied. LazyUpdatesTest test; // The number of readers should be large enough so that it is likely that // several readers will be running at once (with a multiple-core CPU). constexpr int kNumReaders = 8; constexpr int kIters = 100; test.Run(kNumReaders, kIters); } TEST(MutableS2ShapeIndex, MixedGeometry) { // This test used to trigger a bug where the presence of a shape with an // interior could cause shapes that don't have an interior to suddenly // acquire one. This would cause extra S2ShapeIndex cells to be created // that are outside the bounds of the given geometry. vector> polylines; polylines.push_back(MakePolylineOrDie("0:0, 2:1, 0:2, 2:3, 0:4, 2:5, 0:6")); polylines.push_back(MakePolylineOrDie("1:0, 3:1, 1:2, 3:3, 1:4, 3:5, 1:6")); polylines.push_back(MakePolylineOrDie("2:0, 4:1, 2:2, 4:3, 2:4, 4:5, 2:6")); MutableS2ShapeIndex index; for (auto& polyline : polylines) { index.Add(make_unique(std::move(polyline))); } S2Loop loop(S2Cell(S2CellId::Begin(S2CellId::kMaxLevel))); index.Add(make_unique(&loop)); MutableS2ShapeIndex::Iterator it(&index); // No geometry intersects face 1, so there should be no index cells there. EXPECT_EQ(S2CellRelation::DISJOINT, it.Locate(S2CellId::FromFace(1))); } TEST_F(MutableS2ShapeIndexTest, LinearSpace) { // Build an index that requires FLAGS_s2shape_index_min_short_edge_fraction // to be non-zero in order to use a non-quadratic amount of space. // Uncomment the following line to check whether this test works properly. // FLAGS_s2shape_index_min_short_edge_fraction = 0; // Set the maximum number of "short" edges per cell to 1 so that we can // implement this test using a smaller index. MutableS2ShapeIndex::Options options; options.set_max_edges_per_cell(1); index_.Init(options); // The idea is to create O(n) copies of a single long edge, along with O(n) // clusters of (M + 1) points equally spaced along the long edge, where "M" // is the max_edges_per_cell() parameter. The edges are divided such that // there are equal numbers of long and short edges; this maximizes the index // size when FLAGS_s2shape_index_min_short_edge_fraction is set to zero. constexpr int kNumEdges = 100; // Validation is quadratic int edges_per_cluster = options.max_edges_per_cell() + 1; int num_clusters = (kNumEdges / 2) / edges_per_cluster; // Create the long edges. S2Point a(1, 0, 0), b(0, 1, 0); for (int i = 0; i < kNumEdges / 2; ++i) { index_.Add(make_unique(a, b)); } // Create the clusters of short edges. for (int k = 0; k < num_clusters; ++k) { S2Point p = S2::Interpolate(a, b, k / (num_clusters - 1.0)); vector points(edges_per_cluster, p); index_.Add(make_unique(points)); } QuadraticValidate(); // The number of index cells should not exceed the number of clusters. int cell_count = 0; for (MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { ++cell_count; } EXPECT_LE(cell_count, num_clusters); } TEST_F(MutableS2ShapeIndexTest, LongIndexEntriesBound) { // This test demonstrates that the c2 = 366 upper bound (using default // parameter values) mentioned in the .cc file is achievable. // Set the maximum number of "short" edges per cell to 1 so that we can test // using a smaller index. MutableS2ShapeIndex::Options options; options.set_max_edges_per_cell(1); index_.Init(options); // This is a worst-case edge AB that touches as many cells as possible at // level 30 while still being considered "short" at level 29. We create an // index consisting of two copies of this edge plus a full polygon. S2Point a = S2::FaceSiTitoXYZ(0, 0, (1 << 30) + 0).Normalize(); S2Point b = S2::FaceSiTitoXYZ(0, 0, (1 << 30) + 6).Normalize(); for (int i = 0; i < 2; ++i) { index_.Add(make_unique(a, b)); } index_.Add(make_unique(vector>{{}})); // Count the number of index cells at each level. vector counts(S2CellId::kMaxLevel + 1); for (MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); !it.done(); it.Next()) { ++counts[it.id().level()]; } int sum = 0; for (int i = 0; i < counts.size(); ++i) { ABSL_LOG(INFO) << i << ": " << counts[i]; sum += counts[i]; } EXPECT_EQ(sum, 366); } TEST_F(MutableS2ShapeIndexTest, AddRemoveShapeContainingOrigin) { // Add a shape that contains InteriorTracker::Origin(). S2Point origin = S2::FaceUVtoXYZ(0, -1, -1).Normalize(); index_.Add(make_unique( S2Loop::MakeRegularLoop(origin, S1Angle::Degrees(1), 10))); // Force an index update. index_.ForceBuild(); // Remove the shape. index_.Remove(0); // Force another index update. index_.ForceBuild(); // The iterator should be empty. MutableS2ShapeIndex::Iterator it(&index_, S2ShapeIndex::BEGIN); EXPECT_TRUE(it.done()); } TEST_F(MutableS2ShapeIndexTest, DecoderCatchesInvalidIndex) { // An S2Shape index with one face cell but no actual shapes encoded. const std::string encoded{"E\000P\340\010\020\000"}; Decoder decoder(encoded.data(), encoded.size()); MutableS2ShapeIndex index; bool ok = index.Init(&decoder, s2shapeutil::FullDecodeShapeFactory(&decoder)); EXPECT_FALSE(ok); } TEST(S2Shape, user_data) { struct MyData { int x, y; MyData(int _x, int _y) : x(_x), y(_y) {} }; class MyEdgeVectorShape : public S2EdgeVectorShape { public: explicit MyEdgeVectorShape(const MyData& data) : S2EdgeVectorShape(), data_(data) { } const void* user_data() const override { return &data_; } void* mutable_user_data() override { return &data_; } private: MyData data_; }; MyEdgeVectorShape shape(MyData(3, 5)); MyData* data = static_cast(shape.mutable_user_data()); ABSL_DCHECK_EQ(3, data->x); data->y = 10; ABSL_DCHECK_EQ(10, static_cast(shape.user_data())->y); } static void BenchmarkConstruction(benchmark::State& state) { // The intent is not to include the destructor time, but it turns out that // PauseTiming() / ResumeTiming() is so expensive that it is faster to // simply run the destructor when the number of edges is small. int num_edges = state.range(0); bool omit_destructor = num_edges > 100; const string seed_str = absl::StrCat("BENCHMARK_CONSTRUCTION", absl::GetFlag(FLAGS_s2_random_seed)); std::seed_seq seed(seed_str.begin(), seed_str.end()); std::mt19937_64 bitgen(seed); for (auto _ : state) { state.PauseTiming(); { MutableS2ShapeIndex index; unique_ptr loop(S2Loop::MakeRegularLoop( s2random::Point(bitgen), S2Testing::KmToAngle(5), num_edges)); state.ResumeTiming(); index.Add(make_unique(loop.get())); index.ForceBuild(); if (omit_destructor) state.PauseTiming(); } if (omit_destructor) state.ResumeTiming(); } } void BM_Construction(benchmark::State& state) { BenchmarkConstruction(state); } BENCHMARK(BM_Construction)->Arg(4)->Arg(16)->Arg(1024); } // namespace ABSL_FLAG(int32_t, bm_num_edges_per_loop, 100, "Benchmarks: number of edges per loop"); ABSL_FLAG(double, bm_loop_overlap_fraction, 0.0, "Benchmarks: fractional overlap between adjacent loops"); namespace { static void BenchmarkLoopGridAddRelease(benchmark::State& state, int num_edges_per_loop, bool benchmark_release) { int num_loops = state.range(0); int num_loops_per_update = state.range(1); ABSL_CHECK_LE(num_loops_per_update, num_loops); // Construct a grid of loops that optionally overlap. const std::string seed_str = absl::StrCat( "BENCHMARK_LOOP_GRID_ADD_RELEASE", absl::GetFlag(FLAGS_s2_random_seed)); std::seed_seq seed(seed_str.begin(), seed_str.end()); std::mt19937_64 bitgen(seed); int sqrt_num_loops = ceil(sqrt(num_loops)); double max_angle = S2Testing::KmToAngle(100).radians(); double spacing = 2 * max_angle / sqrt_num_loops; // The cos(max_angle) factor ensures that the grids don't overlap when // FLAGS_bm_loop_overlap_fraction is set to zero. double radius = 0.5 * spacing * cos(max_angle) * (1 + absl::GetFlag(FLAGS_bm_loop_overlap_fraction)); MutableS2ShapeIndex index; vector ids; // The shape ids currently in the index. // If "num_loops" is not a perfect square, make the grid slightly larger // and leave some locations empty. int left = num_loops; Matrix3x3_d frame = s2random::Frame(bitgen); for (int i = 0; i < sqrt_num_loops && left > 0; ++i) { for (int j = 0; j < sqrt_num_loops && left > 0; ++j, --left) { S2Point center(tan((i + 0.5) * spacing - max_angle), tan((j + 0.5) * spacing - max_angle), 1.0); const int shape_id = index.Add(make_unique(S2Loop::MakeRegularLoop( S2::FromFrame(frame, center).Normalize(), S1Angle::Radians(radius), num_edges_per_loop))); ids.push_back(shape_id); } } index.ForceBuild(); for (auto _ : state) { state.PauseTiming(); vector> released; for (int j = 0; j < num_loops_per_update; ++j) { size_t k = absl::Uniform(bitgen, 0, ids.size()); released.emplace_back(ids[k], const_cast(index.shape(ids[k]))); ids[k] = ids.back(); ids.pop_back(); } // Either time releasing shapes from the index. if (benchmark_release) state.ResumeTiming(); for (const auto& item : released) { index.Release(item.first).release(); } index.ForceBuild(); // Or time adding them to the index, save their new ids after adding. if (!benchmark_release) state.ResumeTiming(); for (const auto& item : released) { ids.push_back(index.Add(WrapUnique(item.second))); } index.ForceBuild(); } } void BM_IncrementalAddLoopGrid(benchmark::State& state) { BenchmarkLoopGridAddRelease(state, absl::GetFlag(FLAGS_bm_num_edges_per_loop), false /*benchmark_release*/); } BENCHMARK(BM_IncrementalAddLoopGrid) ->ArgPair(10, 1) ->ArgPair(100, 10) ->ArgPair(1000, 1) ->ArgPair(1000, 50); void BM_IncrementalReleaseLoopGrid(benchmark::State& state) { BenchmarkLoopGridAddRelease(state, absl::GetFlag(FLAGS_bm_num_edges_per_loop), true /*benchmark_release*/); } BENCHMARK(BM_IncrementalReleaseLoopGrid) ->ArgPair(10, 1) ->ArgPair(100, 10) ->ArgPair(1000, 1) ->ArgPair(1000, 50); // Tests indexing a fractal with 12,582,912 edges. void BM_BigFractalConstruction(benchmark::State& state) { const string seed_str = absl::StrCat("BIG_FRACTAL_CONSTRUCTION", absl::GetFlag(FLAGS_s2_random_seed)); std::seed_seq seed(seed_str.begin(), seed_str.end()); std::mt19937_64 bitgen(seed); absl::SetFlag(&FLAGS_s2shape_index_tmp_memory_budget, static_cast(state.range(0)) << 20); S2Fractal fractal(bitgen); fractal.set_max_level(11); S2Polygon polygon(fractal.MakeLoop( s2random::FrameAt(bitgen, S2Point(1, 0, 0)), S1Angle::Degrees(40))); for (auto _ : state) { { MutableS2ShapeIndex index; index.Add(make_unique(&polygon)); index.ForceBuild(); state.PauseTiming(); } state.ResumeTiming(); } } BENCHMARK(BM_BigFractalConstruction)->Arg(100 /*MB*/)->Arg(10000 /*MB*/); } // namespace src/s2/r1interval.h000066400000000000000000000205401524103652300144330ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_R1INTERVAL_H_ #define S2_R1INTERVAL_H_ #include #include #include #include #include #include "absl/hash/hash.h" #include "absl/log/absl_check.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/util/math/vector.h" // IWYU pragma: export // An R1Interval represents a closed, bounded interval on the real line. // It is capable of representing the empty interval (containing no points) // and zero-length intervals (containing a single point). // // This class is intended to be copied by value as desired. It uses // the default copy constructor and assignment operator. class R1Interval { public: // Constructor. If lo > hi, the interval is empty. R1Interval(double lo, double hi) : bounds_(lo, hi) {} // The default constructor creates an empty interval. (Any interval where // lo > hi is considered to be empty.) // // Note: Don't construct an interval using the default constructor and // set_lo()/set_hi(), since this technique doesn't work with S1Interval and // is bad programming style anyways. If you need to set both endpoints, use // the constructor above: // // lat_bounds_ = R1Interval(lat_lo, lat_hi); R1Interval() : bounds_(1, 0) {} // Returns an empty interval. static R1Interval Empty() { return R1Interval(); } // Convenience method to construct an interval containing a single point. static R1Interval FromPoint(double p) { return R1Interval(p, p); } // Convenience method to construct the minimal interval containing // the two given points. This is equivalent to starting with an empty // interval and calling AddPoint() twice, but it is more efficient. static R1Interval FromPointPair(double p1, double p2) { if (p1 <= p2) { return R1Interval(p1, p2); } else { return R1Interval(p2, p1); } } // The low bound of the interval. double lo() const { return bounds_[0]; } // The high bound of the interval. double hi() const { return bounds_[1]; } // Methods to modify one endpoint of an existing R1Interval. Do not use // these methods if you want to replace both endpoints of the interval; use // a constructor instead. For example: // // *lat_bounds = R1Interval(lat_lo, lat_hi); void set_lo(double p) { bounds_[0] = p; } void set_hi(double p) { bounds_[1] = p; } // Methods that allow the R1Interval to be accessed as a vector. (The // recommended style is to use lo() and hi() whenever possible, but these // methods are useful when the endpoint to be selected is not constant.) double operator[](int i) const { return bounds_[i]; } double& operator[](int i) { return bounds_[i]; } const Vector2_d& bounds() const { return bounds_; } Vector2_d* mutable_bounds() { return &bounds_; } // Return true if the interval is empty, i.e. it contains no points. bool is_empty() const { return lo() > hi(); } // Return the center of the interval. For empty intervals, // the result is arbitrary. double GetCenter() const { return 0.5 * (lo() + hi()); } // Return the length of the interval. The length of an empty interval // is negative. double GetLength() const { return hi() - lo(); } // Returns true if the given point is in the closed interval [lo, hi]. bool Contains(double p) const { return p >= lo() && p <= hi(); } // Returns true if the given point is in the open interval (lo, hi). bool InteriorContains(double p) const { return p > lo() && p < hi(); } // Return true if this interval contains the interval 'y'. bool Contains(const R1Interval& y) const { if (y.is_empty()) return true; return y.lo() >= lo() && y.hi() <= hi(); } // Return true if the interior of this interval contains the entire // interval 'y' (including its boundary). bool InteriorContains(const R1Interval& y) const { if (y.is_empty()) return true; return y.lo() > lo() && y.hi() < hi(); } // Return true if this interval intersects the given interval, // i.e. if they have any points in common. bool Intersects(const R1Interval& y) const { if (lo() <= y.lo()) { return y.lo() <= hi() && y.lo() <= y.hi(); } else { return lo() <= y.hi() && lo() <= hi(); } } // Return true if the interior of this interval intersects // any point of the given interval (including its boundary). bool InteriorIntersects(const R1Interval& y) const { return y.lo() < hi() && lo() < y.hi() && lo() < hi() && y.lo() <= y.hi(); } // Return the Hausdorff distance to the given interval 'y'. For two // R1Intervals x and y, this distance is defined as // h(x, y) = max_{p in x} min_{q in y} d(p, q). double GetDirectedHausdorffDistance(const R1Interval& y) const { if (is_empty()) return 0.0; if (y.is_empty()) return HUGE_VAL; return std::max(0.0, std::max(hi() - y.hi(), y.lo() - lo())); } // Expand the interval so that it contains the given point "p". void AddPoint(double p) { if (is_empty()) { set_lo(p); set_hi(p); } else if (p < lo()) { set_lo(p); } else if (p > hi()) { set_hi(p); } } // Expand the interval so that it contains the given interval "y". void AddInterval(const R1Interval& y) { if (y.is_empty()) return; if (is_empty()) { *this = y; return; } if (y.lo() < lo()) set_lo(y.lo()); if (y.hi() > hi()) set_hi(y.hi()); } // Return the closest point in the interval to the given point "p". // The interval must be non-empty. double Project(double p) const { ABSL_DCHECK(!is_empty()); return std::clamp(p, lo(), hi()); } // Return an interval that has been expanded on each side by the given // distance "margin". If "margin" is negative, then shrink the interval on // each side by "margin" instead. The resulting interval may be empty. Any // expansion of an empty interval remains empty. R1Interval Expanded(double margin) const { if (is_empty()) return *this; return R1Interval(lo() - margin, hi() + margin); } // Return the smallest interval that contains this interval and the // given interval "y". R1Interval Union(const R1Interval& y) const { if (is_empty()) return y; if (y.is_empty()) return *this; return R1Interval(std::min(lo(), y.lo()), std::max(hi(), y.hi())); } // Return the intersection of this interval with the given interval. // Empty intervals do not need to be special-cased. R1Interval Intersection(const R1Interval& y) const { return R1Interval(std::max(lo(), y.lo()), std::min(hi(), y.hi())); } // Return true if two intervals contain the same set of points. bool operator==(const R1Interval& y) const { return (lo() == y.lo() && hi() == y.hi()) || (is_empty() && y.is_empty()); } // Return true if two intervals do not contain the same set of points. bool operator!=(const R1Interval& y) const { return !operator==(y); } // Return true if this interval can be transformed into the given interval // by moving each endpoint by at most "max_error". The empty interval is // considered to be positioned arbitrarily on the real line, thus any // interval with (length <= 2*max_error) matches the empty interval. bool ApproxEquals(const R1Interval& y, double max_error = 1e-15) const { if (is_empty()) return y.GetLength() <= 2 * max_error; if (y.is_empty()) return GetLength() <= 2 * max_error; return (std::fabs(y.lo() - lo()) <= max_error && std::fabs(y.hi() - hi()) <= max_error); } private: Vector2_d bounds_; }; inline std::ostream& operator<<(std::ostream& os, const R1Interval& x) { return os << "[" << x.lo() << ", " << x.hi() << "]"; } template H AbslHashValue(H h, const R1Interval& interval) { return H::combine(std::move(h), interval.lo(), interval.hi()); } #endif // S2_R1INTERVAL_H_ src/s2/r1interval_test.cc000066400000000000000000000166151524103652300156400ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/r1interval.h" #include #include #include #include "absl/hash/hash_testing.h" #include "absl/strings/string_view.h" using absl::string_view; static void TestIntervalOps(const R1Interval& x, const R1Interval& y, string_view expected) { // Test all of the interval operations on the given pair of intervals. // "expected" is a sequence of "T" and "F" characters corresponding to // the expected results of Contains(), InteriorContains(), Intersects(), // and InteriorIntersects() respectively. EXPECT_EQ(expected[0] == 'T', x.Contains(y)); EXPECT_EQ(expected[1] == 'T', x.InteriorContains(y)); EXPECT_EQ(expected[2] == 'T', x.Intersects(y)); EXPECT_EQ(expected[3] == 'T', x.InteriorIntersects(y)); EXPECT_EQ(x.Contains(y), x.Union(y) == x); EXPECT_EQ(x.Intersects(y), !x.Intersection(y).is_empty()); R1Interval z = x; z.AddInterval(y); EXPECT_EQ(x.Union(y), z); } TEST(R1Interval, TestBasic) { // Constructors and accessors. R1Interval unit(0, 1); R1Interval negunit(-1, 0); EXPECT_EQ(0, unit.lo()); EXPECT_EQ(1, unit.hi()); EXPECT_EQ(-1, negunit[0]); EXPECT_EQ(0, negunit[1]); R1Interval ten(0, 0); ten.set_hi(10); EXPECT_EQ(R1Interval(0, 10), ten); ten[0] = -10; EXPECT_EQ(R1Interval(-10, 10), ten); ten[1] = 0; EXPECT_EQ(Vector2_d(-10, 0), ten.bounds()); *ten.mutable_bounds() = Vector2_d(0, 10); EXPECT_EQ(R1Interval(0, 10), ten); // is_empty() R1Interval half(0.5, 0.5); EXPECT_FALSE(unit.is_empty()); EXPECT_FALSE(half.is_empty()); R1Interval empty = R1Interval::Empty(); EXPECT_TRUE(empty.is_empty()); // == and != EXPECT_TRUE(empty == empty); EXPECT_TRUE(unit == unit); EXPECT_TRUE(unit != empty); EXPECT_TRUE(R1Interval(1, 2) != R1Interval(1, 3)); // Check that the default R1Interval is identical to Empty(). R1Interval default_empty; EXPECT_TRUE(default_empty.is_empty()); EXPECT_EQ(empty.lo(), default_empty.lo()); EXPECT_EQ(empty.hi(), default_empty.hi()); // GetCenter(), GetLength() EXPECT_EQ(unit.GetCenter(), 0.5); EXPECT_EQ(half.GetCenter(), 0.5); EXPECT_EQ(negunit.GetLength(), 1.0); EXPECT_EQ(half.GetLength(), 0); EXPECT_LT(empty.GetLength(), 0); // Contains(double), InteriorContains(double) EXPECT_TRUE(unit.Contains(0.5)); EXPECT_TRUE(unit.InteriorContains(0.5)); EXPECT_TRUE(unit.Contains(0)); EXPECT_FALSE(unit.InteriorContains(0)); EXPECT_TRUE(unit.Contains(1)); EXPECT_FALSE(unit.InteriorContains(1)); // Contains(R1Interval), InteriorContains(R1Interval) // Intersects(R1Interval), InteriorIntersects(R1Interval) { SCOPED_TRACE(""); TestIntervalOps(empty, empty, "TTFF"); } { SCOPED_TRACE(""); TestIntervalOps(empty, unit, "FFFF"); } { SCOPED_TRACE(""); TestIntervalOps(unit, half, "TTTT"); } { SCOPED_TRACE(""); TestIntervalOps(unit, unit, "TFTT"); } { SCOPED_TRACE(""); TestIntervalOps(unit, empty, "TTFF"); } { SCOPED_TRACE(""); TestIntervalOps(unit, negunit, "FFTF"); } { SCOPED_TRACE(""); TestIntervalOps(unit, R1Interval(0, 0.5), "TFTT"); } { SCOPED_TRACE(""); TestIntervalOps(half, R1Interval(0, 0.5), "FFTF"); } // AddPoint() R1Interval r = empty; r.AddPoint(5); EXPECT_EQ(5, r.lo()); EXPECT_EQ(5, r.hi()); r.AddPoint(-1); EXPECT_EQ(-1, r.lo()); EXPECT_EQ(5, r.hi()); r.AddPoint(0); EXPECT_EQ(-1, r.lo()); EXPECT_EQ(5, r.hi()); // Project() EXPECT_EQ(0.3, R1Interval(0.1, 0.4).Project(0.3)); EXPECT_EQ(0.1, R1Interval(0.1, 0.4).Project(-7.0)); EXPECT_EQ(0.4, R1Interval(0.1, 0.4).Project(0.6)); // FromPointPair() EXPECT_EQ(R1Interval(4, 4), R1Interval::FromPointPair(4, 4)); EXPECT_EQ(R1Interval(-2, -1), R1Interval::FromPointPair(-1, -2)); EXPECT_EQ(R1Interval(-5, 3), R1Interval::FromPointPair(-5, 3)); // Expanded() EXPECT_EQ(empty, empty.Expanded(0.45)); EXPECT_EQ(R1Interval(-0.5, 1.5), unit.Expanded(0.5)); EXPECT_EQ(R1Interval(0.5, 0.5), unit.Expanded(-0.5)); EXPECT_TRUE(unit.Expanded(-0.51).is_empty()); EXPECT_TRUE(unit.Expanded(-0.51).Expanded(0.51).is_empty()); // Union(), Intersection() EXPECT_EQ(R1Interval(99, 100), R1Interval(99, 100).Union(empty)); EXPECT_EQ(R1Interval(99, 100), empty.Union(R1Interval(99, 100))); EXPECT_TRUE(R1Interval(5, 3).Union(R1Interval(0, -2)).is_empty()); EXPECT_TRUE(R1Interval(0, -2).Union(R1Interval(5, 3)).is_empty()); EXPECT_EQ(unit, unit.Union(unit)); EXPECT_EQ(R1Interval(-1, 1), unit.Union(negunit)); EXPECT_EQ(R1Interval(-1, 1), negunit.Union(unit)); EXPECT_EQ(unit, half.Union(unit)); EXPECT_EQ(half, unit.Intersection(half)); EXPECT_EQ(R1Interval(0, 0), unit.Intersection(negunit)); EXPECT_TRUE(negunit.Intersection(half).is_empty()); EXPECT_TRUE(unit.Intersection(empty).is_empty()); EXPECT_TRUE(empty.Intersection(unit).is_empty()); } TEST(R1Interval, ApproxEquals) { // Choose two values kLo and kHi such that it's okay to shift an endpoint by // kLo (i.e., the resulting interval is equivalent) but not by kHi. static const double kLo = 4 * DBL_EPSILON; // < max_error default static const double kHi = 6 * DBL_EPSILON; // > max_error default // Empty intervals. R1Interval empty = R1Interval::Empty(); EXPECT_TRUE(empty.ApproxEquals(empty)); EXPECT_TRUE(R1Interval(0, 0).ApproxEquals(empty)); EXPECT_TRUE(empty.ApproxEquals(R1Interval(0, 0))); EXPECT_TRUE(R1Interval(1, 1).ApproxEquals(empty)); EXPECT_TRUE(empty.ApproxEquals(R1Interval(1, 1))); EXPECT_FALSE(empty.ApproxEquals(R1Interval(0, 1))); EXPECT_TRUE(empty.ApproxEquals(R1Interval(1, 1 + 2*kLo))); EXPECT_FALSE(empty.ApproxEquals(R1Interval(1, 1 + 2*kHi))); // Singleton intervals. EXPECT_TRUE(R1Interval(1, 1).ApproxEquals(R1Interval(1, 1))); EXPECT_TRUE(R1Interval(1, 1).ApproxEquals(R1Interval(1 - kLo, 1 - kLo))); EXPECT_TRUE(R1Interval(1, 1).ApproxEquals(R1Interval(1 + kLo, 1 + kLo))); EXPECT_FALSE(R1Interval(1, 1).ApproxEquals(R1Interval(1 - kHi, 1))); EXPECT_FALSE(R1Interval(1, 1).ApproxEquals(R1Interval(1, 1 + kHi))); EXPECT_TRUE(R1Interval(1, 1).ApproxEquals(R1Interval(1 - kLo, 1 + kLo))); EXPECT_FALSE(R1Interval(0, 0).ApproxEquals(R1Interval(1, 1))); // Other intervals. EXPECT_TRUE(R1Interval(1 - kLo, 2 + kLo).ApproxEquals(R1Interval(1, 2))); EXPECT_TRUE(R1Interval(1 + kLo, 2 - kLo).ApproxEquals(R1Interval(1, 2))); EXPECT_FALSE(R1Interval(1 - kHi, 2 + kLo).ApproxEquals(R1Interval(1, 2))); EXPECT_FALSE(R1Interval(1 + kHi, 2 - kLo).ApproxEquals(R1Interval(1, 2))); EXPECT_FALSE(R1Interval(1 - kLo, 2 + kHi).ApproxEquals(R1Interval(1, 2))); EXPECT_FALSE(R1Interval(1 + kLo, 2 - kHi).ApproxEquals(R1Interval(1, 2))); } TEST(R1Interval, SupportsAbslHash) { EXPECT_TRUE(absl::VerifyTypeImplementsAbslHashCorrectly({ R1Interval::Empty(), R1Interval(0, 0), R1Interval(0, 1), R1Interval(1, 2), R1Interval(-1, 1), R1Interval(0.5, 1.5), })); } src/s2/r2.h000066400000000000000000000023031524103652300126640ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_R2_H_ #define S2_R2_H_ #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/util/math/vector.h" // IWYU pragma: export using R2Point = Vector2_d; // An edge in R2 space. struct R2Edge { R2Edge() = default; R2Edge(const R2Point& v0, const R2Point& v1) : v0(v0), v1(v1) {} bool operator==(const R2Edge& b) const { return v0 == b.v0 && v1 == b.v1; } template friend H AbslHashValue(H h, const R2Edge& e) { return H::combine(std::move(h), e.v0, e.v1); } R2Point v0; R2Point v1; }; #endif // S2_R2_H_ src/s2/r2rect.cc000066400000000000000000000053331524103652300137060ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/r2rect.h" #include #include "s2/r1interval.h" #include "s2/r2.h" R2Rect R2Rect::FromCenterSize(const R2Point& center, const R2Point& size) { return R2Rect(R1Interval(center.x() - 0.5 * size.x(), center.x() + 0.5 * size.x()), R1Interval(center.y() - 0.5 * size.y(), center.y() + 0.5 * size.y())); } bool R2Rect::Contains(const R2Rect& other) const { return x().Contains(other.x()) && y().Contains(other.y()); } bool R2Rect::InteriorContains(const R2Rect& other) const { return x().InteriorContains(other.x()) && y().InteriorContains(other.y()); } bool R2Rect::Intersects(const R2Rect& other) const { return x().Intersects(other.x()) && y().Intersects(other.y()); } bool R2Rect::InteriorIntersects(const R2Rect& other) const { return x().InteriorIntersects(other.x()) && y().InteriorIntersects(other.y()); } void R2Rect::AddPoint(const R2Point& p) { bounds_[0].AddPoint(p[0]); bounds_[1].AddPoint(p[1]); } void R2Rect::AddRect(const R2Rect& other) { bounds_[0].AddInterval(other[0]); bounds_[1].AddInterval(other[1]); } R2Point R2Rect::Project(const R2Point& p) const { return R2Point(x().Project(p.x()), y().Project(p.y())); } R2Rect R2Rect::Expanded(const R2Point& margin) const { R1Interval xx = x().Expanded(margin.x()); R1Interval yy = y().Expanded(margin.y()); if (xx.is_empty() || yy.is_empty()) return Empty(); return R2Rect(xx, yy); } R2Rect R2Rect::Union(const R2Rect& other) const { return R2Rect(x().Union(other.x()), y().Union(other.y())); } R2Rect R2Rect::Intersection(const R2Rect& other) const { R1Interval xx = x().Intersection(other.x()); R1Interval yy = y().Intersection(other.y()); if (xx.is_empty() || yy.is_empty()) return Empty(); return R2Rect(xx, yy); } bool R2Rect::ApproxEquals(const R2Rect& other, double max_error) const { return (x().ApproxEquals(other.x(), max_error) && y().ApproxEquals(other.y(), max_error)); } std::ostream& operator<<(std::ostream& os, const R2Rect& r) { return os << "[Lo" << r.lo() << ", Hi" << r.hi() << "]"; } src/s2/r2rect.h000066400000000000000000000217731524103652300135560ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_R2RECT_H_ #define S2_R2RECT_H_ #include #include #include "absl/hash/hash.h" #include "absl/log/absl_check.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/r1interval.h" #include "s2/r2.h" // An R2Rect represents a closed axis-aligned rectangle in the (x,y) plane. // // This class is intended to be copied by value as desired. It uses // the default copy constructor and assignment operator. class R2Rect { public: // Construct a rectangle from the given lower-left and upper-right points. R2Rect(const R2Point& lo, const R2Point& hi); // Construct a rectangle from the given intervals in x and y. The two // intervals must either be both empty or both non-empty. R2Rect(const R1Interval& x, const R1Interval& y); // The default constructor creates an empty R2Rect. R2Rect(); // The canonical empty rectangle. Use is_empty() to test for empty // rectangles, since they have more than one representation. static R2Rect Empty(); // Construct a rectangle from a center point and size in each dimension. // Both components of size should be non-negative, i.e. this method cannot // be used to create an empty rectangle. static R2Rect FromCenterSize(const R2Point& center, const R2Point& size); // Convenience method to construct a rectangle containing a single point. static R2Rect FromPoint(const R2Point& p); // Convenience method to construct the minimal bounding rectangle containing // the two given points. This is equivalent to starting with an empty // rectangle and calling AddPoint() twice. Note that it is different than // the R2Rect(lo, hi) constructor, where the first point is always // used as the lower-left corner of the resulting rectangle. static R2Rect FromPointPair(const R2Point& p1, const R2Point& p2); // Accessor methods. const R1Interval& x() const { return bounds_[0]; } const R1Interval& y() const { return bounds_[1]; } R2Point lo() const { return R2Point(x().lo(), y().lo()); } R2Point hi() const { return R2Point(x().hi(), y().hi()); } // Methods that allow the R2Rect to be accessed as a vector. const R1Interval& operator[](int i) const { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 2); return bounds_[i]; } R1Interval& operator[](int i) { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 2); return bounds_[i]; } // Return true if the rectangle is valid, which essentially just means // that if the bound for either axis is empty then both must be. bool is_valid() const; // Return true if the rectangle is empty, i.e. it contains no points at all. bool is_empty() const; // Return the k-th vertex of the rectangle (k = 0,1,2,3) in CCW order. // Vertex 0 is in the lower-left corner. For convenience, the argument is // reduced modulo 4 to the range [0..3]. R2Point GetVertex(int k) const; // Return the vertex in direction "i" along the x-axis (0=left, 1=right) and // direction "j" along the y-axis (0=down, 1=up). Equivalently, return the // vertex constructed by selecting endpoint "i" of the x-interval (0=lo, // 1=hi) and vertex "j" of the y-interval. R2Point GetVertex(int i, int j) const; // Return the center of the rectangle in (x,y)-space. R2Point GetCenter() const; // Return the width and height of this rectangle in (x,y)-space. Empty // rectangles have a negative width and height. R2Point GetSize() const; // Return true if the rectangle contains the given point. Note that // rectangles are closed regions, i.e. they contain their boundary. bool Contains(const R2Point& p) const; // Return true if and only if the given point is contained in the interior // of the region (i.e. the region excluding its boundary). bool InteriorContains(const R2Point& p) const; // Return true if and only if the rectangle contains the given other // rectangle. bool Contains(const R2Rect& other) const; // Return true if and only if the interior of this rectangle contains all // points of the given other rectangle (including its boundary). bool InteriorContains(const R2Rect& other) const; // Return true if this rectangle and the given other rectangle have any // points in common. bool Intersects(const R2Rect& other) const; // Return true if and only if the interior of this rectangle intersects // any point (including the boundary) of the given other rectangle. bool InteriorIntersects(const R2Rect& other) const; // Expand the rectangle to include the given point. The rectangle is // expanded by the minimum amount possible. void AddPoint(const R2Point& p); // Expand the rectangle to include the given other rectangle. This is the // same as replacing the rectangle by the union of the two rectangles, but // is somewhat more efficient. void AddRect(const R2Rect& other); // Return the closest point in the rectangle to the given point "p". // The rectangle must be non-empty. R2Point Project(const R2Point& p) const; // Return a rectangle that has been expanded on each side in the x-direction // by margin.x(), and on each side in the y-direction by margin.y(). If // either margin is negative, then shrink the interval on the corresponding // sides instead. The resulting rectangle may be empty. Any expansion of // an empty rectangle remains empty. R2Rect Expanded(const R2Point& margin) const; R2Rect Expanded(double margin) const; // Return the smallest rectangle containing the union of this rectangle and // the given rectangle. R2Rect Union(const R2Rect& other) const; // Return the smallest rectangle containing the intersection of this // rectangle and the given rectangle. R2Rect Intersection(const R2Rect& other) const; // Return true if two rectangles contains the same set of points. bool operator==(const R2Rect& other) const; // Return true if two rectangles do not contain the same set of points. bool operator!=(const R2Rect& other) const; // Return true if the x- and y-intervals of the two rectangles are the same // up to the given tolerance (see r1interval.h for details). bool ApproxEquals(const R2Rect& other, double max_error = 1e-15) const; private: R1Interval bounds_[2]; }; inline R2Rect::R2Rect(const R2Point& lo, const R2Point& hi) { bounds_[0] = R1Interval(lo.x(), hi.x()); bounds_[1] = R1Interval(lo.y(), hi.y()); ABSL_DCHECK(is_valid()); } inline R2Rect::R2Rect(const R1Interval& x, const R1Interval& y) { bounds_[0] = x; bounds_[1] = y; ABSL_DCHECK(is_valid()); } inline R2Rect::R2Rect() { // The default R1Interval constructor creates an empty interval. ABSL_DCHECK(is_valid()); } inline R2Rect R2Rect::Empty() { return R2Rect(R1Interval::Empty(), R1Interval::Empty()); } inline R2Rect R2Rect::FromPointPair(const R2Point& p1, const R2Point& p2) { return R2Rect(R1Interval::FromPointPair(p1.x(), p2.x()), R1Interval::FromPointPair(p1.y(), p2.y())); } inline bool R2Rect::is_valid() const { // The x/y ranges must either be both empty or both non-empty. return x().is_empty() == y().is_empty(); } inline bool R2Rect::is_empty() const { return x().is_empty(); } inline R2Rect R2Rect::FromPoint(const R2Point& p) { return R2Rect(p, p); } inline R2Point R2Rect::GetVertex(int k) const { // Twiddle bits to return the points in CCW order (lower left, lower right, // upper right, upper left). int j = (k >> 1) & 1; return GetVertex(j ^ (k & 1), j); } inline R2Point R2Rect::GetVertex(int i, int j) const { return R2Point(bounds_[0][i], bounds_[1][j]); } inline R2Point R2Rect::GetCenter() const { return R2Point(x().GetCenter(), y().GetCenter()); } inline R2Point R2Rect::GetSize() const { return R2Point(x().GetLength(), y().GetLength()); } inline bool R2Rect::Contains(const R2Point& p) const { return x().Contains(p.x()) && y().Contains(p.y()); } inline bool R2Rect::InteriorContains(const R2Point& p) const { return x().InteriorContains(p.x()) && y().InteriorContains(p.y()); } inline R2Rect R2Rect::Expanded(double margin) const { return Expanded(R2Point(margin, margin)); } inline bool R2Rect::operator==(const R2Rect& other) const { return x() == other.x() && y() == other.y(); } inline bool R2Rect::operator!=(const R2Rect& other) const { return !operator==(other); } std::ostream& operator<<(std::ostream& os, const R2Rect& r); template H AbslHashValue(H h, const R2Rect& rect) { return H::combine(std::move(h), rect.x(), rect.y()); } #endif // S2_R2RECT_H_ src/s2/r2rect_test.cc000066400000000000000000000222421524103652300147430ustar00rootroot00000000000000// Copyright 2012 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) // // Most of the R2Rect methods have trivial implementations in terms of the // R1Interval class, so most of the testing is done in that unit test. #include "s2/r2rect.h" #include #include #include "absl/hash/hash_testing.h" #include "absl/strings/string_view.h" #include "s2/r1interval.h" #include "s2/r2.h" using absl::string_view; static void TestIntervalOps(const R2Rect& x, const R2Rect& y, string_view expected_rexion, const R2Rect& expected_union, const R2Rect& expected_intersection) { // Test all of the interval operations on the given pair of intervals. // "expected_rexion" is a sequence of "T" and "F" characters corresponding // to the expected results of Contains(), InteriorContains(), Intersects(), // and InteriorIntersects() respectively. EXPECT_EQ(expected_rexion[0] == 'T', x.Contains(y)); EXPECT_EQ(expected_rexion[1] == 'T', x.InteriorContains(y)); EXPECT_EQ(expected_rexion[2] == 'T', x.Intersects(y)); EXPECT_EQ(expected_rexion[3] == 'T', x.InteriorIntersects(y)); EXPECT_EQ(x.Union(y) == x, x.Contains(y)); EXPECT_EQ(!x.Intersection(y).is_empty(), x.Intersects(y)); EXPECT_EQ(expected_union, x.Union(y)); EXPECT_EQ(expected_intersection, x.Intersection(y)); R2Rect r = x; r.AddRect(y); EXPECT_EQ(expected_union, r); if (y.GetSize() == R2Point(0, 0)) { r = x; r.AddPoint(y.lo()); EXPECT_EQ(expected_union, r); } } TEST(R2Rect, EmptyRectangles) { // Test basic properties of empty rectangles. R2Rect empty = R2Rect::Empty(); EXPECT_TRUE(empty.is_valid()); EXPECT_TRUE(empty.is_empty()); EXPECT_EQ(empty, empty); } TEST(R2Rect, ConstructorsAndAccessors) { // Check various constructors and accessor methods. R2Rect r = R2Rect(R2Point(0.1, 0), R2Point(0.25, 1)); EXPECT_EQ(0.1, r.x().lo()); EXPECT_EQ(0.25, r.x().hi()); EXPECT_EQ(0.0, r.y().lo()); EXPECT_EQ(1.0, r.y().hi()); EXPECT_EQ(0.1, r[0][0]); EXPECT_EQ(0.25, r[0][1]); EXPECT_EQ(0.0, r[1][0]); EXPECT_EQ(1.0, r[1][1]); EXPECT_EQ(R1Interval(0.1, 0.25), r.x()); EXPECT_EQ(R1Interval(0, 1), r.y()); EXPECT_EQ(R1Interval(0.1, 0.25), r[0]); EXPECT_EQ(R1Interval(0, 1), r[1]); r[0] = R1Interval(3, 4); r[1][0] = 5; r[1][1] = 6; EXPECT_EQ(R1Interval(3, 4), r[0]); EXPECT_EQ(R1Interval(5, 6), r[1]); EXPECT_EQ(r, r); EXPECT_NE(r, R2Rect::Empty()); R2Rect r2; EXPECT_TRUE(r2.is_empty()); EXPECT_EQ(r2, R2Rect::Empty()); } TEST(R2Rect, FromCenterSize) { // FromCenterSize() EXPECT_TRUE(R2Rect::FromCenterSize(R2Point(0.3, 0.5), R2Point(0.2, 0.4)). ApproxEquals(R2Rect(R2Point(0.2, 0.3), R2Point(0.4, 0.7)))); EXPECT_TRUE(R2Rect::FromCenterSize(R2Point(1, 0.1), R2Point(0, 2)). ApproxEquals(R2Rect(R2Point(1, -0.9), R2Point(1, 1.1)))); } TEST(R2Rect, FromPoint) { // FromPoint(), FromPointPair() R2Rect d1 = R2Rect(R2Point(0.1, 0), R2Point(0.25, 1)); EXPECT_EQ(R2Rect(d1.lo(), d1.lo()), R2Rect::FromPoint(d1.lo())); EXPECT_EQ(R2Rect(R2Point(0.15, 0.3), R2Point(0.35, 0.9)), R2Rect::FromPointPair(R2Point(0.15, 0.9), R2Point(0.35, 0.3))); EXPECT_EQ(R2Rect(R2Point(0.12, 0), R2Point(0.83, 0.5)), R2Rect::FromPointPair(R2Point(0.83, 0), R2Point(0.12, 0.5))); } TEST(R2Rect, SimplePredicates) { // GetCenter(), GetVertex(), Contains(R2Point), InteriorContains(R2Point). R2Point sw1 = R2Point(0, 0.25); R2Point ne1 = R2Point(0.5, 0.75); R2Rect r1(sw1, ne1); EXPECT_EQ(R2Point(0.25, 0.5), r1.GetCenter()); EXPECT_EQ(R2Point(0, 0.25), r1.GetVertex(0)); EXPECT_EQ(R2Point(0.5, 0.25), r1.GetVertex(1)); EXPECT_EQ(R2Point(0.5, 0.75), r1.GetVertex(2)); EXPECT_EQ(R2Point(0, 0.75), r1.GetVertex(3)); EXPECT_TRUE(r1.Contains(R2Point(0.2, 0.4))); EXPECT_FALSE(r1.Contains(R2Point(0.2, 0.8))); EXPECT_FALSE(r1.Contains(R2Point(-0.1, 0.4))); EXPECT_FALSE(r1.Contains(R2Point(0.6, 0.1))); EXPECT_TRUE(r1.Contains(sw1)); EXPECT_TRUE(r1.Contains(ne1)); EXPECT_FALSE(r1.InteriorContains(sw1)); EXPECT_FALSE(r1.InteriorContains(ne1)); // Make sure that GetVertex() returns vertices in CCW order. for (int k = 0; k < 4; ++k) { R2Point a = r1.GetVertex(k - 1); R2Point b = r1.GetVertex(k); R2Point c = r1.GetVertex(k + 1); EXPECT_GT((b - a).Ortho().DotProd(c - a), 0); } } TEST(R2Rect, IntervalOperations) { // Contains(R2Rect), InteriorContains(R2Rect), // Intersects(), InteriorIntersects(), Union(), Intersection(). // // Much more testing of these methods is done in s1interval_test // and r1interval_test. R2Rect empty = R2Rect::Empty(); R2Point sw1 = R2Point(0, 0.25); R2Point ne1 = R2Point(0.5, 0.75); R2Rect r1(sw1, ne1); R2Rect r1_mid = R2Rect(R2Point(0.25, 0.5), R2Point(0.25, 0.5)); R2Rect r_sw1(sw1, sw1); R2Rect r_ne1(ne1, ne1); TestIntervalOps(r1, r1_mid, "TTTT", r1, r1_mid); TestIntervalOps(r1, r_sw1, "TFTF", r1, r_sw1); TestIntervalOps(r1, r_ne1, "TFTF", r1, r_ne1); EXPECT_EQ(R2Rect(R2Point(0, 0.25), R2Point(0.5, 0.75)), r1); TestIntervalOps(r1, R2Rect(R2Point(0.45, 0.1), R2Point(0.75, 0.3)), "FFTT", R2Rect(R2Point(0, 0.1), R2Point(0.75, 0.75)), R2Rect(R2Point(0.45, 0.25), R2Point(0.5, 0.3))); TestIntervalOps(r1, R2Rect(R2Point(0.5, 0.1), R2Point(0.7, 0.3)), "FFTF", R2Rect(R2Point(0, 0.1), R2Point(0.7, 0.75)), R2Rect(R2Point(0.5, 0.25), R2Point(0.5, 0.3))); TestIntervalOps(r1, R2Rect(R2Point(0.45, 0.1), R2Point(0.7, 0.25)), "FFTF", R2Rect(R2Point(0, 0.1), R2Point(0.7, 0.75)), R2Rect(R2Point(0.45, 0.25), R2Point(0.5, 0.25))); TestIntervalOps(R2Rect(R2Point(0.1, 0.2), R2Point(0.1, 0.3)), R2Rect(R2Point(0.15, 0.7), R2Point(0.2, 0.8)), "FFFF", R2Rect(R2Point(0.1, 0.2), R2Point(0.2, 0.8)), empty); // Check that the intersection of two rectangles that overlap in x but not y // is valid, and vice versa. TestIntervalOps(R2Rect(R2Point(0.1, 0.2), R2Point(0.4, 0.5)), R2Rect(R2Point(0, 0), R2Point(0.2, 0.1)), "FFFF", R2Rect(R2Point(0, 0), R2Point(0.4, 0.5)), empty); TestIntervalOps(R2Rect(R2Point(0, 0), R2Point(0.1, 0.3)), R2Rect(R2Point(0.2, 0.1), R2Point(0.3, 0.4)), "FFFF", R2Rect(R2Point(0, 0), R2Point(0.3, 0.4)), empty); } TEST(R2Rect, AddPoint) { // AddPoint() R2Point sw1 = R2Point(0, 0.25); R2Point ne1 = R2Point(0.5, 0.75); R2Rect r1(sw1, ne1); R2Rect r2 = R2Rect::Empty(); r2.AddPoint(R2Point(0, 0.25)); r2.AddPoint(R2Point(0.5, 0.25)); r2.AddPoint(R2Point(0, 0.75)); r2.AddPoint(R2Point(0.1, 0.4)); EXPECT_EQ(r1, r2); } TEST(R2Rect, Project) { R2Rect r1(R1Interval(0, 0.5), R1Interval(0.25, 0.75)); EXPECT_EQ(R2Point(0, 0.25), r1.Project(R2Point(-0.01, 0.24))); EXPECT_EQ(R2Point(0, 0.48), r1.Project(R2Point(-5.0, 0.48))); EXPECT_EQ(R2Point(0, 0.75), r1.Project(R2Point(-5.0, 2.48))); EXPECT_EQ(R2Point(0.19, 0.75), r1.Project(R2Point(0.19, 2.48))); EXPECT_EQ(R2Point(0.5, 0.75), r1.Project(R2Point(6.19, 2.48))); EXPECT_EQ(R2Point(0.5, 0.53), r1.Project(R2Point(6.19, 0.53))); EXPECT_EQ(R2Point(0.5, 0.25), r1.Project(R2Point(6.19, -2.53))); EXPECT_EQ(R2Point(0.33, 0.25), r1.Project(R2Point(0.33, -2.53))); EXPECT_EQ(R2Point(0.33, 0.37), r1.Project(R2Point(0.33, 0.37))); } TEST(R2Rect, Expanded) { // Expanded() EXPECT_TRUE(R2Rect::Empty().Expanded(R2Point(0.1, 0.3)).is_empty()); EXPECT_TRUE(R2Rect::Empty().Expanded(R2Point(-0.1, -0.3)).is_empty()); EXPECT_TRUE(R2Rect(R2Point(0.2, 0.4), R2Point(0.3, 0.7)). Expanded(R2Point(0.1, 0.3)). ApproxEquals(R2Rect(R2Point(0.1, 0.1), R2Point(0.4, 1.0)))); EXPECT_TRUE(R2Rect(R2Point(0.2, 0.4), R2Point(0.3, 0.7)). Expanded(R2Point(-0.1, 0.3)).is_empty()); EXPECT_TRUE(R2Rect(R2Point(0.2, 0.4), R2Point(0.3, 0.7)). Expanded(R2Point(0.1, -0.2)).is_empty()); EXPECT_TRUE(R2Rect(R2Point(0.2, 0.4), R2Point(0.3, 0.7)). Expanded(R2Point(0.1, -0.1)). ApproxEquals(R2Rect(R2Point(0.1, 0.5), R2Point(0.4, 0.6)))); EXPECT_TRUE(R2Rect(R2Point(0.2, 0.4), R2Point(0.3, 0.7)).Expanded(0.1). ApproxEquals(R2Rect(R2Point(0.1, 0.3), R2Point(0.4, 0.8)))); } TEST(R2Rect, SupportsAbslHash) { EXPECT_TRUE(absl::VerifyTypeImplementsAbslHashCorrectly({ R2Rect::Empty(), R2Rect(R2Point(0, 0), R2Point(0, 0)), R2Rect(R2Point(0, 0), R2Point(1, 1)), R2Rect(R2Point(1, 2), R2Point(3, 4)), R2Rect(R2Point(-1, -2), R2Point(1, 2)), R2Rect(R1Interval(0, 1), R1Interval(2, 3)), })); } src/s2/s1angle.cc000066400000000000000000000034401524103652300140340ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s1angle.h" #include #include #include "absl/strings/str_format.h" #include "s2/util/coding/coder.h" #include "s2/s2error.h" #include "s2/s2latlng.h" #include "s2/s2point.h" S1Angle::S1Angle(const S2Point& x, const S2Point& y) : radians_(x.Angle(y)) { } S1Angle::S1Angle(const S2LatLng& x, const S2LatLng& y) : radians_(x.GetDistance(y).radians()) { } S1Angle S1Angle::Normalized() const { S1Angle a(radians_); a.Normalize(); return a; } void S1Angle::Normalize() { radians_ = remainder(radians_, 2.0 * M_PI); if (radians_ <= -M_PI) radians_ = M_PI; } void S1Angle::Coder::Encode(Encoder& encoder, const S1Angle& angle) const { encoder.Ensure(sizeof(double)); encoder.putdouble(angle.radians()); } bool S1Angle::Coder::Decode(Decoder& decoder, S1Angle& angle, S2Error& error) const { if (decoder.avail() < sizeof(double)) { error = S2Error::DataLoss("Could not decode S1Angle."); return false; } angle = Radians(decoder.getdouble()); return true; } std::ostream& operator<<(std::ostream& os, S1Angle a) { return os << absl::StreamFormat("%.7f", a.degrees()); } src/s2/s1angle.h000066400000000000000000000320121524103652300136730ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_S1ANGLE_H_ #define S2_S1ANGLE_H_ #include #include #include #include #include #include "absl/hash/hash.h" #include "absl/log/absl_check.h" #include "s2/util/coding/coder.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s2coder.h" #include "s2/s2error.h" #include "s2/s2point.h" #include "s2/util/math/mathutil.h" class S2LatLng; // This class represents a one-dimensional angle (as opposed to a // two-dimensional solid angle). It has methods for converting angles to // or from radians, degrees, and the E5/E6/E7 representations (i.e. degrees // multiplied by 1e5/1e6/1e7 and rounded to the nearest integer). // // The internal representation is a double-precision value in radians, so // conversion to and from radians is exact. Conversions between E5, E6, E7, // and Degrees are not always exact; for example, Degrees(3.1) is different // from E6(3100000) or E7(31000000). However, the following properties are // guaranteed for any integer "n", provided that "n" is in the input range of // both functions: // // Degrees(n) == E6(1000000 * n) // Degrees(n) == E7(10000000 * n) // E6(n) == E7(10 * n) // // The corresponding properties are *not* true for E5, so if you use E5 then // don't test for exact equality when comparing to other formats such as // Degrees or E7. // // The following conversions between degrees and radians are exact: // // Degrees(180) == Radians(M_PI) // Degrees(45 * k) == Radians(k * M_PI / 4) for k == 0..8 // // These identities also hold when the arguments are scaled up or down by any // power of 2. Some similar identities are also true, for example, // Degrees(60) == Radians(M_PI / 3), but be aware that this type of identity // does not hold in general. For example, Degrees(3) != Radians(M_PI / 60). // // Similarly, the conversion to radians means that Angle::Degrees(x).degrees() // does not always equal "x". For example, // // S1Angle::Degrees(45 * k).degrees() == 45 * k for k == 0..8 // but S1Angle::Degrees(60).degrees() != 60. // // This means that when testing for equality, you should allow for numerical // errors (EXPECT_DOUBLE_EQ) or convert to discrete E5/E6/E7 values first. // // CAVEAT: All of the above properties depend on "double" being the usual // 64-bit IEEE 754 type (which is true on almost all modern platforms). // // This class is intended to be copied by value as desired. It uses // the default copy constructor and assignment operator. class S1Angle { public: // These methods construct S1Angle objects from their measure in radians // or degrees. static constexpr S1Angle Radians(double radians); static constexpr S1Angle Degrees(double degrees); static constexpr S1Angle E5(int32_t e5); static constexpr S1Angle E6(int32_t e6); static constexpr S1Angle E7(int32_t e7); // Convenience functions -- to use when args have been fixed32s in protos. // // The arguments are static_cast into int32_t, so very large unsigned values // are treated as negative numbers. static constexpr S1Angle UnsignedE6(uint32_t e6); static constexpr S1Angle UnsignedE7(uint32_t e7); // The default constructor yields a zero angle. This is useful for STL // containers and class methods with output arguments. constexpr S1Angle() = default; // Return an angle larger than any finite angle. static constexpr S1Angle Infinity(); // A explicit shorthand for the default constructor. static constexpr S1Angle Zero(); // Return the angle between two points, which is also equal to the distance // between these points on the unit sphere. The points do not need to be // normalized. This function has a maximum error of 3.25 * DBL_EPSILON (or // 2.5 * DBL_EPSILON for angles up to 1 radian). If either point is // zero-length (e.g. an uninitialized S2Point), or almost zero-length, the // resulting angle will be zero. S1Angle(const S2Point& x, const S2Point& y); // Like the constructor above, but return the angle (i.e., distance) between // two S2LatLng points. This function has about 15 digits of accuracy for // small distances but only about 8 digits of accuracy as the distance // approaches 180 degrees (i.e., nearly-antipodal points). S1Angle(const S2LatLng& x, const S2LatLng& y); constexpr double radians() const; constexpr double degrees() const; // Returns the E5/E6/E7 representation (i.e. degrees multiplied by // 1e5/1e6/1e7 and rounded to the nearest integer). The angle in degrees // must be in the interval (-180, 180]. (`Normalize` and `Normalized` // will ensure this.) int32_t e5() const; int32_t e6() const; int32_t e7() const; // Return the absolute value of an angle. S1Angle abs() const; friend S1Angle abs(S1Angle a); #ifndef SWIG // `friend operator`s are incompatible with SWIG 4.0, but work with 4.3. // Comparison operators. friend constexpr bool operator==(S1Angle x, S1Angle y); #if defined(__cpp_impl_three_way_comparison) && \ __cpp_impl_three_way_comparison >= 201907L // This should be `= default`, but can't be due to PyCLIF limitations. // NOLINTNEXTLINE(clang-diagnostic-pre-c++20-compat) friend constexpr auto operator<=>(S1Angle x, S1Angle y) { // NOLINTNEXTLINE(clang-diagnostic-pre-c++20-compat) return x.radians() <=> y.radians(); } #else friend constexpr bool operator!=(S1Angle x, S1Angle y) { return x.radians() != y.radians(); } friend constexpr bool operator<(S1Angle x, S1Angle y) { return x.radians() < y.radians(); } friend constexpr bool operator>(S1Angle x, S1Angle y) { return x.radians() > y.radians(); } friend constexpr bool operator<=(S1Angle x, S1Angle y) { return x.radians() <= y.radians(); } friend constexpr bool operator>=(S1Angle x, S1Angle y) { return x.radians() >= y.radians(); } #endif // Simple arithmetic operators for manipulating S1Angles. friend constexpr S1Angle operator-(S1Angle a); friend constexpr S1Angle operator+(S1Angle a, S1Angle b); friend constexpr S1Angle operator-(S1Angle a, S1Angle b); friend constexpr S1Angle operator*(double m, S1Angle a); friend constexpr S1Angle operator*(S1Angle a, double m); friend constexpr S1Angle operator/(S1Angle a, double m); friend constexpr double operator/(S1Angle a, S1Angle b); #endif // !SWIG S1Angle& operator+=(S1Angle a); S1Angle& operator-=(S1Angle a); S1Angle& operator*=(double m); S1Angle& operator/=(double m); // Trigonometric functions (not necessary but slightly more convenient). friend double sin(S1Angle a); friend double cos(S1Angle a); friend double tan(S1Angle a); struct SinCosPair { double sin; double cos; }; // Return the sine and cosine of the angle. This may be more efficient than // calling sin() and cos() separately. SinCosPair SinCos() const; // Returns true if the angle is in the normalized range (-180, 180] // degrees, which is the valid input range for e5(), e6(), and e7(). bool IsNormalized() const; // Return the angle normalized to the range (-180, 180] degrees. S1Angle Normalized() const; // Normalize this angle to the range (-180, 180] degrees. void Normalize(); // Class for encoding and decoding the object when used in Flume pipelines. class Coder : public s2coding::S2Coder { public: void Encode(Encoder& encoder, const S1Angle& angle) const override; bool Decode(Decoder& decoder, S1Angle& angle, S2Error& error) const override; }; // When S1Angle is used as a key in one of the absl::btree container types, // indicate that linear rather than binary search should be used. This is // much faster when the comparison function is cheap. typedef std::true_type absl_btree_prefer_linear_node_search; private: explicit constexpr S1Angle(double radians) : radians_(radians) {} double radians_ = 0.0; }; ////////////////// Implementation details follow //////////////////// inline constexpr S1Angle S1Angle::Infinity() { return S1Angle(std::numeric_limits::infinity()); } inline constexpr S1Angle S1Angle::Zero() { return S1Angle(0); } inline constexpr double S1Angle::radians() const { return radians_; } inline constexpr double S1Angle::degrees() const { return (180 / M_PI) * radians_; } // Note that the E5, E6, and E7 conversion involve two multiplications rather // than one. This is mainly for backwards compatibility (changing this would // break many tests), but it does have the nice side effect that conversions // between Degrees, E6, and E7 are exact when the arguments are integers. inline int32_t S1Angle::e5() const { // TODO(user,b/298298095): Tighten this to (-180, 180] (see IsNormalized). ABSL_DCHECK_LE(std::numeric_limits::min() / 1e5, degrees()); ABSL_DCHECK_LE(degrees(), std::numeric_limits::max() / 1e5); return MathUtil::Round(1e5 * degrees()); } inline int32_t S1Angle::e6() const { ABSL_DCHECK_LE(std::numeric_limits::min() / 1e6, degrees()); ABSL_DCHECK_LE(degrees(), std::numeric_limits::max() / 1e6); return MathUtil::Round(1e6 * degrees()); } inline int32_t S1Angle::e7() const { ABSL_DCHECK_LE(std::numeric_limits::min() / 1e7, degrees()); ABSL_DCHECK_LE(degrees(), std::numeric_limits::max() / 1e7); return MathUtil::Round(1e7 * degrees()); } inline bool S1Angle::IsNormalized() const { return radians() > -M_PI && radians() <= M_PI; } inline S1Angle S1Angle::abs() const { return S1Angle(std::fabs(radians_)); } inline S1Angle abs(S1Angle a) { return S1Angle(std::fabs(a.radians_)); } inline constexpr bool operator==(S1Angle x, S1Angle y) { return x.radians() == y.radians(); } inline constexpr S1Angle operator-(S1Angle a) { return S1Angle::Radians(-a.radians()); } inline constexpr S1Angle operator+(S1Angle a, S1Angle b) { return S1Angle::Radians(a.radians() + b.radians()); } inline constexpr S1Angle operator-(S1Angle a, S1Angle b) { return S1Angle::Radians(a.radians() - b.radians()); } inline constexpr S1Angle operator*(double m, S1Angle a) { return S1Angle::Radians(m * a.radians()); } inline constexpr S1Angle operator*(S1Angle a, double m) { return S1Angle::Radians(m * a.radians()); } inline constexpr S1Angle operator/(S1Angle a, double m) { return S1Angle::Radians(a.radians() / m); } inline constexpr double operator/(S1Angle a, S1Angle b) { return a.radians() / b.radians(); } inline S1Angle& S1Angle::operator+=(S1Angle a) { radians_ += a.radians(); return *this; } inline S1Angle& S1Angle::operator-=(S1Angle a) { radians_ -= a.radians(); return *this; } inline S1Angle& S1Angle::operator*=(double m) { radians_ *= m; return *this; } inline S1Angle& S1Angle::operator/=(double m) { radians_ /= m; return *this; } inline double sin(S1Angle a) { return sin(a.radians()); } inline double cos(S1Angle a) { return cos(a.radians()); } inline double tan(S1Angle a) { return tan(a.radians()); } inline S1Angle::SinCosPair S1Angle::SinCos() const { // TODO(b/370513151): Remove once Clang can optimize this. // NB: __sincos() provided by __APPLE__ is not bit-identical to sin(), cos() // under `--config=darwin_arm64`. Windows does not support sincos(). // `sincos` gives different results on Ubuntu 22. Disable for glibc until // this can be narrowed down further. // https://github.com/google/s2geometry/issues/413 #if defined(__ANDROID__) double sin_angle, cos_angle; sincos(radians(), &sin_angle, &cos_angle); return {sin_angle, cos_angle}; #else return {sin(radians()), cos(radians())}; #endif } inline constexpr S1Angle S1Angle::Radians(double radians) { return S1Angle(radians); } inline constexpr S1Angle S1Angle::Degrees(double degrees) { return S1Angle((M_PI / 180) * degrees); } inline constexpr S1Angle S1Angle::E5(int32_t e5) { return Degrees(1e-5 * e5); } inline constexpr S1Angle S1Angle::E6(int32_t e6) { return Degrees(1e-6 * e6); } inline constexpr S1Angle S1Angle::E7(int32_t e7) { return Degrees(1e-7 * e7); } inline constexpr S1Angle S1Angle::UnsignedE6(uint32_t e6) { return E6(static_cast(e6)); } inline constexpr S1Angle S1Angle::UnsignedE7(uint32_t e7) { return E7(static_cast(e7)); } // Writes the angle in degrees with 7 digits of precision after the // decimal point, e.g. "17.3745904". std::ostream& operator<<(std::ostream& os, S1Angle a); template H AbslHashValue(H h, S1Angle angle) { return H::combine(std::move(h), angle.radians()); } #endif // S2_S1ANGLE_H_ src/s2/s1angle_test.cc000066400000000000000000000251251524103652300150770ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s1angle.h" #include #include #include #include #include #include "absl/hash/hash_testing.h" #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "s2/s2error.h" #include "s2/s2latlng.h" #include "s2/s2point.h" #include "s2/s2testing.h" #include "s2/util/coding/coder.h" TEST(S1Angle, DefaultConstructor) { // Check that the default constructor returns an angle of 0. S1Angle a; EXPECT_EQ(0, a.radians()); } TEST(S1Angle, Infinity) { EXPECT_LT(S1Angle::Radians(1e30), S1Angle::Infinity()); EXPECT_LT(-S1Angle::Infinity(), S1Angle::Zero()); EXPECT_EQ(S1Angle::Infinity(), S1Angle::Infinity()); } TEST(S1Angle, Zero) { EXPECT_EQ(S1Angle::Radians(0), S1Angle::Zero()); } TEST(S1Angle, PiRadiansExactly180Degrees) { // Check that the conversion between Pi radians and 180 degrees is exact. EXPECT_EQ(M_PI, S1Angle::Radians(M_PI).radians()); EXPECT_EQ(180.0, S1Angle::Radians(M_PI).degrees()); EXPECT_EQ(M_PI, S1Angle::Degrees(180).radians()); EXPECT_EQ(180.0, S1Angle::Degrees(180).degrees()); EXPECT_EQ(90.0, S1Angle::Radians(M_PI_2).degrees()); // Check negative angles. EXPECT_EQ(-90.0, S1Angle::Radians(-M_PI_2).degrees()); EXPECT_EQ(-M_PI_4, S1Angle::Degrees(-45).radians()); } TEST(S1Angle, E5E6E7Representations) { // Check that E5/E6/E7 representations work as expected. EXPECT_DOUBLE_EQ(S1Angle::Degrees(-45).radians(), S1Angle::E5(-4500000).radians()); EXPECT_DOUBLE_EQ(S1Angle::Degrees(-60).radians(), S1Angle::E6(-60000000).radians()); EXPECT_DOUBLE_EQ(S1Angle::Degrees(75).radians(), S1Angle::E7(750000000).radians()); EXPECT_EQ(-17256123, S1Angle::Degrees(-172.56123).e5()); EXPECT_EQ(12345678, S1Angle::Degrees(12.345678).e6()); EXPECT_EQ(-123456789, S1Angle::Degrees(-12.3456789).e7()); } TEST(S1Angle, E6E7RepresentationsUnsigned) { // Check that unsigned E6/E7 representations work as expected. EXPECT_DOUBLE_EQ( S1Angle::Degrees(60).radians(), S1Angle::UnsignedE6(static_cast(60000000)).radians()); EXPECT_DOUBLE_EQ( S1Angle::Degrees(-60).radians(), S1Angle::UnsignedE6(static_cast(-60000000)).radians()); EXPECT_DOUBLE_EQ( S1Angle::Degrees(75).radians(), S1Angle::UnsignedE7(static_cast(750000000)).radians()); EXPECT_DOUBLE_EQ( S1Angle::Degrees(-75).radians(), S1Angle::UnsignedE7(static_cast(-750000000)).radians()); } TEST(S1Angle, NormalizeCorrectlyCanonicalizesAngles) { EXPECT_DOUBLE_EQ(0.0, S1Angle::Degrees(360.0).Normalized().degrees()); EXPECT_DOUBLE_EQ(-90.0, S1Angle::Degrees(-90.0).Normalized().degrees()); EXPECT_DOUBLE_EQ(180.0, S1Angle::Degrees(-180.0).Normalized().degrees()); EXPECT_DOUBLE_EQ(180.0, S1Angle::Degrees(180.0).Normalized().degrees()); EXPECT_DOUBLE_EQ(180.0, S1Angle::Degrees(540.0).Normalized().degrees()); EXPECT_DOUBLE_EQ(90.0, S1Angle::Degrees(-270.0).Normalized().degrees()); } TEST(S1Angle, ArithmeticOperationsOnAngles) { EXPECT_DOUBLE_EQ(0.3, S1Angle::Radians(-0.3).abs().radians()); EXPECT_DOUBLE_EQ(0.3, abs(S1Angle::Radians(-0.3)).radians()); EXPECT_DOUBLE_EQ(-0.1, (-S1Angle::Radians(0.1)).radians()); EXPECT_DOUBLE_EQ(0.4, (S1Angle::Radians(0.1) + S1Angle::Radians(0.3)).radians()); EXPECT_DOUBLE_EQ(-0.2, (S1Angle::Radians(0.1) - S1Angle::Radians(0.3)).radians()); EXPECT_DOUBLE_EQ(0.6, (2 * S1Angle::Radians(0.3)).radians()); EXPECT_DOUBLE_EQ(0.6, (S1Angle::Radians(0.3) * 2).radians()); EXPECT_DOUBLE_EQ(0.15, (S1Angle::Radians(0.3) / 2).radians()); EXPECT_DOUBLE_EQ(0.5, (S1Angle::Radians(0.3) / S1Angle::Radians(0.6))); S1Angle tmp = S1Angle::Radians(1.0); tmp += S1Angle::Radians(0.5); EXPECT_DOUBLE_EQ(1.5, tmp.radians()); tmp -= S1Angle::Radians(1.0); EXPECT_DOUBLE_EQ(0.5, tmp.radians()); tmp *= 5; EXPECT_DOUBLE_EQ(2.5, tmp.radians()); tmp /= 2; EXPECT_DOUBLE_EQ(1.25, tmp.radians()); } TEST(S1Angle, Trigonometry) { // Spot check a few angles to ensure that the correct function is called. EXPECT_DOUBLE_EQ(1, cos(S1Angle::Degrees(0))); EXPECT_DOUBLE_EQ(1, sin(S1Angle::Degrees(90))); EXPECT_DOUBLE_EQ(1, tan(S1Angle::Degrees(45))); // Expect that SinCos is exactly [sin, cos]. for (int k = -1000; k <= 1000; ++k) { const S1Angle angle = S1Angle::Degrees(k); const S1Angle::SinCosPair sin_cos = angle.SinCos(); // If this fails once, it will likely fail many times. ASSERT_EQ(sin_cos.sin, sin(angle)) << k; ASSERT_EQ(sin_cos.cos, cos(angle)) << k; } } TEST(S1Angle, ConstructorsThatMeasureAngles) { EXPECT_DOUBLE_EQ(M_PI_2, S1Angle(S2Point(1, 0, 0), S2Point(0, 0, 2)).radians()); EXPECT_DOUBLE_EQ(0.0, S1Angle(S2Point(1, 0, 0), S2Point(1, 0, 0)).radians()); EXPECT_NEAR(50.0, S1Angle(S2LatLng::FromDegrees(20, 20), S2LatLng::FromDegrees(70, 20)).degrees(), 1e-13); } TEST(S1Angle, TestFormatting) { std::ostringstream ss; ss << S1Angle::Degrees(180.0); EXPECT_EQ("180.0000000", ss.str()); } TEST(S1Angle, RoundtripEncodingSucceeds) { S1Angle angle = S1Angle::Radians(4.4); Encoder encoder; S1Angle::Coder().Encode(encoder, angle); S1Angle decoded_angle; S2Error error; Decoder decoder(encoder.base(), encoder.length()); EXPECT_TRUE(S1Angle::Coder().Decode(decoder, decoded_angle, error)); EXPECT_EQ(angle, decoded_angle); } TEST(S1Angle, DecodeFailsWithTruncatedBuffer) { S1Angle angle = S1Angle::Radians(1.1); Encoder encoder; S1Angle::Coder().Encode(encoder, angle); S1Angle decoded_angle; S2Error error; Decoder decoder(encoder.base(), encoder.length() - 2); EXPECT_FALSE(S1Angle::Coder().Decode(decoder, decoded_angle, error)); } // Benchmarks to verify that the conversion to E5/E6/E7 is not much slower // than the conversion from E5/E6/E7. (Float-to-integer conversions can be // quite slow on some platforms.) We only check the times for E6; the times // for E5/E7 should be similar. // Inspect the results to make sure that the To/From E6 times are not // much different. The difference factor slightly less than 2 on an x86_64. // To reduce the impact of loop overhead, we do kOpsPerLoop ops per loop. static constexpr int kOpsPerLoop = 8; static void BM_E6ToRadians(benchmark::State& state) { // Time conversion from E6 to radians. int i = 0; while (state.KeepRunningBatch(kOpsPerLoop)) { benchmark::DoNotOptimize(S1Angle::E6(i + 0).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 1).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 2).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 3).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 4).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 5).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 6).radians()); benchmark::DoNotOptimize(S1Angle::E6(i + 7).radians()); i += kOpsPerLoop; } } BENCHMARK(BM_E6ToRadians); static void BM_RadiansToE6(benchmark::State& state) { // Time conversion from radians to E6. const double delta = (2 * M_PI) / (state.max_iterations + kOpsPerLoop); double angle = -M_PI; while (state.KeepRunningBatch(kOpsPerLoop)) { // clang-format off benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; benchmark::DoNotOptimize(S1Angle::Radians(angle).e6()); angle += delta; // clang-format on } } BENCHMARK(BM_RadiansToE6); // The current implementation guarantees exact conversions between // Degrees() and E6() when the Degrees() argument is an integer. TEST(S1Angle, DegreesVsE6) { for (int i = 0; i <= 180; ++i) { EXPECT_EQ(S1Angle::Degrees(i), S1Angle::E6(1000000 * i)); } } // The current implementation guarantees exact conversions between // Degrees() and E7() when the Degrees() argument is an integer. TEST(S1Angle, DegreesVsE7) { for (int i = 0; i <= 180; ++i) { EXPECT_EQ(S1Angle::Degrees(i), S1Angle::E7(10000000 * i)); } } // The current implementation guarantees exact conversions between // E6() and E7() when the E6() argument is an integer. TEST(S1Angle, E6VsE7) { absl::BitGen bitgen( S2Testing::MakeTaggedSeedSeq("E6_VS_E7", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); for (int iter = 0; iter < 1000; ++iter) { int i = absl::Uniform(bitgen, 0, 180000000); EXPECT_EQ(S1Angle::E6(i), S1Angle::E7(10 * i)); } } // The current implementation guarantees certain exact conversions between // degrees and radians (see the header file for details). TEST(S1Angle, DegreesVsRadians) { for (int k = -8; k <= 8; ++k) { EXPECT_EQ(S1Angle::Degrees(45 * k), S1Angle::Radians(k * M_PI / 4)); EXPECT_EQ(45 * k, S1Angle::Degrees(45 * k).degrees()); } for (int k = 0; k <= 30; ++k) { int n = 1 << k; EXPECT_EQ(S1Angle::Degrees(180. / n), S1Angle::Radians(M_PI / n)); EXPECT_EQ(S1Angle::Degrees(60. / n), S1Angle::Radians(M_PI / (3. * n))); EXPECT_EQ(S1Angle::Degrees(36. / n), S1Angle::Radians(M_PI / (5. * n))); EXPECT_EQ(S1Angle::Degrees(20. / n), S1Angle::Radians(M_PI / (9. * n))); EXPECT_EQ(S1Angle::Degrees(4. / n), S1Angle::Radians(M_PI / (45. * n))); } // We also spot check a couple of non-identities. EXPECT_NE(S1Angle::Degrees(3), S1Angle::Radians(M_PI / 60)); EXPECT_NE(60, S1Angle::Degrees(60).degrees()); } TEST(S1Angle, SupportsAbslHash) { EXPECT_TRUE(absl::VerifyTypeImplementsAbslHashCorrectly({ S1Angle::Zero(), S1Angle::Radians(1), S1Angle::Radians(-1), S1Angle::Degrees(90), S1Angle::Degrees(180), S1Angle::Degrees(-90), S1Angle::Infinity(), })); } src/s2/s1chord_angle.cc000066400000000000000000000127501524103652300152170ustar00rootroot00000000000000// Copyright 2013 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s1chord_angle.h" #include #include #include #include #include "absl/log/absl_check.h" #include "s2/s1angle.h" using std::max; using std::min; using std::nextafter; static constexpr double kMaxLength2 = 4.0; S1Angle S1ChordAngle::ToAngle() const { if (is_negative()) return S1Angle::Radians(-1); if (is_infinity()) return S1Angle::Infinity(); return S1Angle::Radians(2 * asin(0.5 * sqrt(length2_))); } S1ChordAngle S1ChordAngle::Successor() const { if (length2_ >= kMaxLength2) return Infinity(); if (length2_ < 0.0) return Zero(); return S1ChordAngle(nextafter(length2_, 10.0)); } S1ChordAngle S1ChordAngle::Predecessor() const { if (length2_ <= 0.0) return Negative(); if (length2_ > kMaxLength2) return Straight(); return S1ChordAngle(nextafter(length2_, -10.0)); } S1ChordAngle S1ChordAngle::PlusError(double error) const { // If angle is Negative() or Infinity(), don't change it. // Otherwise clamp it to the valid range. if (is_special()) return *this; return S1ChordAngle(max(0.0, min(kMaxLength2, length2_ + error))); } double S1ChordAngle::GetS2PointConstructorMaxError() const { // There is a relative error of 2.5 * DBL_EPSILON when computing the squared // distance, plus a relative error of 2 * DBL_EPSILON and an absolute error // of (16 * DBL_EPSILON**2) because the lengths of the input points may // differ from 1 by up to (2 * DBL_EPSILON) each. (This is the maximum // length error in S2Point::Normalize.) return 4.5 * DBL_EPSILON * length2_ + 16 * DBL_EPSILON * DBL_EPSILON; } double S1ChordAngle::GetS1AngleConstructorMaxError() const { // Assuming that an accurate math library is being used, the sin() call and // the multiply each have a relative error of 0.5 * DBL_EPSILON. However // the sin() error is squared. return 1.5 * DBL_EPSILON * length2_; } S1ChordAngle operator+(S1ChordAngle a, S1ChordAngle b) { // Error Analysis: // // u is the unit round-off, equal to ε/2 = 2^-53 // x and y below are both computed with (1+u)² error. So we have // length2 = x + y + 2*sqrt(x * y) // length2 = ((x + y)(1+u)³ + 2*sqrt((x * y)((1+u)³))(1+u))(1+u) // // Taking (1+u)^1.5 out of the square root and rounding (1+u)^2.5 to (1+u)³: // length2 = (x + y + 2*sqrt(x * y))(1+u)⁴ // // Bounding (1+u)⁴ as 4*1.01u = 4.04*ε/2 = 2.02ε, total relative error is: // length2()*2.02ε. // Note that this method is much more efficient than converting the chord // angles to S1Angles and adding those. It requires only one square root // plus a few additions and multiplications. ABSL_DCHECK(!a.is_special()) << a; ABSL_DCHECK(!b.is_special()) << b; // Optimization for the common case where "b" is an error tolerance // parameter that happens to be set to zero. double a2 = a.length2(), b2 = b.length2(); if (b2 == 0) return a; // Clamp the angle sum to at most 180 degrees. if (a2 + b2 >= kMaxLength2) return S1ChordAngle::Straight(); // Let "a" and "b" be the (non-squared) chord lengths, and let c = a+b. // Let A, B, and C be the corresponding half-angles (a = 2*sin(A), etc). // Then the formula below can be derived from c = 2 * sin(A+B) and the // relationships sin(A+B) = sin(A)*cos(B) + sin(B)*cos(A) // cos(X) = sqrt(1 - sin^2(X)) . double x = a2 * (1 - 0.25 * b2); // is_valid() => non-negative double y = b2 * (1 - 0.25 * a2); // is_valid() => non-negative return S1ChordAngle(min(kMaxLength2, x + y + 2 * sqrt(x * y))); } S1ChordAngle operator-(S1ChordAngle a, S1ChordAngle b) { // See comments in operator+(). ABSL_DCHECK(!a.is_special()) << a; ABSL_DCHECK(!b.is_special()) << b; double a2 = a.length2(), b2 = b.length2(); if (b2 == 0) return a; if (a2 <= b2) return S1ChordAngle::Zero(); double x = a2 * (1 - 0.25 * b2); double y = b2 * (1 - 0.25 * a2); // The calculation below is formulated differently (with two square roots // rather than one) to avoid excessive cancellation error when two nearly // equal values are subtracted. double c = max(0.0, sqrt(x) - sqrt(y)); return S1ChordAngle(c * c); } double sin2(S1ChordAngle a) { ABSL_DCHECK(!a.is_special()); // Let "a" be the (non-squared) chord length, and let A be the corresponding // half-angle (a = 2*sin(A)). The formula below can be derived from: // sin(2*A) = 2 * sin(A) * cos(A) // cos^2(A) = 1 - sin^2(A) // This is much faster than converting to an angle and computing its sine. return a.length2() * (1 - 0.25 * a.length2()); } double sin(S1ChordAngle a) { return sqrt(sin2(a)); } double cos(S1ChordAngle a) { // cos(2*A) = cos^2(A) - sin^2(A) = 1 - 2*sin^2(A) ABSL_DCHECK(!a.is_special()); return 1 - 0.5 * a.length2(); } double tan(S1ChordAngle a) { return sin(a) / cos(a); } std::ostream& operator<<(std::ostream& os, S1ChordAngle a) { return os << a.ToAngle(); } src/s2/s1chord_angle.h000066400000000000000000000416651524103652300150700ustar00rootroot00000000000000// Copyright 2013 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_S1CHORD_ANGLE_H_ #define S2_S1CHORD_ANGLE_H_ #include #include #include #include #include #include #include #include "absl/log/absl_check.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s1angle.h" #include "s2/s2point.h" #include "s2/s2pointutil.h" // S1ChordAngle represents the angle subtended by a chord (i.e., the straight // line segment connecting two points on the sphere). Its representation // makes it very efficient for computing and comparing distances, but unlike // S1Angle it is only capable of representing angles between 0 and Pi radians. // S1ChordAngle is intended for applications where many angles need to be // computed and compared, otherwise it is simpler to use S1Angle. // // S1ChordAngle also loses some accuracy as the angle approaches Pi radians. // There are several different ways to measure this error, including the // representational error (i.e., how accurately S1ChordAngle can represent // angles near Pi radians), the conversion error (i.e., how much precision is // lost when an S1Angle is converted to an S1ChordAngle), and the measurement // error (i.e., how accurate the S1ChordAngle(a, b) constructor is when the // points A and B are separated by angles close to Pi radians). All of these // errors differ by a small constant factor. // // For the measurement error (which is the largest of these errors and also // the most important in practice), let the angle between A and B be (Pi - x) // radians, i.e. A and B are within "x" radians of being antipodal. The // corresponding chord length is // // r = 2 * sin((Pi - x) / 2) = 2 * cos(x / 2) . // // For values of x not close to Pi the relative error in the squared chord // length is at most 4.5 * DBL_EPSILON (see GetS2PointConstructorMaxError). // The relative error in "r" is thus at most 2.25 * DBL_EPSILON ~= 5e-16. To // convert this error into an equivalent angle, we have // // |dr / dx| = sin(x / 2) // // and therefore // // |dx| = dr / sin(x / 2) // = 5e-16 * (2 * cos(x / 2)) / sin(x / 2) // = 1e-15 / tan(x / 2) // // The maximum error is attained when // // x = |dx| // = 1e-15 / tan(x / 2) // ~= 1e-15 / (x / 2) // ~= sqrt(2e-15) // // In summary, the measurement error for an angle (Pi - x) is at most // // dx = min(1e-15 / tan(x / 2), sqrt(2e-15)) // (~= min(2e-15 / x, sqrt(2e-15)) when x is small). // // On the Earth's surface (assuming a radius of 6371km), this corresponds to // the following worst-case measurement errors: // // Accuracy: Unless antipodal to within: // --------- --------------------------- // 6.4 nanometers 10,000 km (90 degrees) // 1 micrometer 81.2 kilometers // 1 millimeter 81.2 meters // 1 centimeter 8.12 meters // 28.5 centimeters 28.5 centimeters // // The representational and conversion errors referred to earlier are somewhat // smaller than this. For example, maximum distance between adjacent // representable S1ChordAngle values is only 13.5 cm rather than 28.5 cm. To // see this, observe that the closest representable value to r^2 = 4 is // r^2 = 4 * (1 - DBL_EPSILON / 2). Thus r = 2 * (1 - DBL_EPSILON / 4) and // the angle between these two representable values is // // x = 2 * acos(r / 2) // = 2 * acos(1 - DBL_EPSILON / 4) // ~= 2 * asin(sqrt(DBL_EPSILON / 2) // ~= sqrt(2 * DBL_EPSILON) // ~= 2.1e-8 // // which is 13.5 cm on the Earth's surface. // // The worst case rounding error occurs when the value halfway between these // two representable values is rounded up to 4. This halfway value is // r^2 = (4 * (1 - DBL_EPSILON / 4)), thus r = 2 * (1 - DBL_EPSILON / 8) and // the worst case rounding error is // // x = 2 * acos(r / 2) // = 2 * acos(1 - DBL_EPSILON / 8) // ~= 2 * asin(sqrt(DBL_EPSILON / 4) // ~= sqrt(DBL_EPSILON) // ~= 1.5e-8 // // which is 9.5 cm on the Earth's surface. // // This class is intended to be copied by value as desired. It uses // the default copy constructor and assignment operator. class S1ChordAngle { public: // Maximum relative error when summing two S1ChordAngles together. // Absolute error is length2() of the summed S1ChordAngle() times this value. // See the definition of operator+() for the error analysis. static constexpr double kRelativeSumError = 2.02 * DBL_EPSILON; // The default constructor yields a zero angle. This is useful for STL // containers and class methods with output arguments. constexpr S1ChordAngle() = default; // Construct the S1ChordAngle corresponding to the distance between the two // given points. The points must be unit length. S1ChordAngle(const S2Point& x, const S2Point& y); // Return the zero chord angle. static constexpr S1ChordAngle Zero(); // Return a chord angle of 90 degrees (a "right angle"). static constexpr S1ChordAngle Right(); // Return a chord angle of 180 degrees (a "straight angle"). This is the // maximum finite chord angle. static constexpr S1ChordAngle Straight(); // Return a chord angle larger than any finite chord angle. The only valid // operations on Infinity() are comparisons, S1Angle conversions, and // Successor() / Predecessor(). static constexpr S1ChordAngle Infinity(); // Return a chord angle smaller than Zero(). The only valid operations on // Negative() are comparisons, S1Angle conversions, and Successor() / // Predecessor(). static constexpr S1ChordAngle Negative(); // Conversion from an S1Angle. Angles outside the range [0, Pi] are handled // as follows: Infinity() is mapped to Infinity(), negative angles are // mapped to Negative(), and finite angles larger than Pi are mapped to // Straight(). // // Note that this operation is relatively expensive and should be avoided. // To use S1ChordAngle effectively, you should structure your code so that // input arguments are converted to S1ChordAngles at the beginning of your // algorithm, and results are converted back to S1Angles only at the end. explicit S1ChordAngle(S1Angle angle); // Convenience methods implemented by converting from an S1Angle. static S1ChordAngle Radians(double radians); static S1ChordAngle Degrees(double degrees); static S1ChordAngle E5(int32_t e5); static S1ChordAngle E6(int32_t e6); static S1ChordAngle E7(int32_t e7); // Construct an S1ChordAngle that is an upper bound on the given S1Angle, // i.e. such that FastUpperBoundFrom(x).ToAngle() >= x. Unlike the S1Angle // constructor above, this method is very fast, and the bound is accurate to // within 1% for distances up to about 3100km on the Earth's surface. static constexpr S1ChordAngle FastUpperBoundFrom(S1Angle angle); // Construct an S1ChordAngle from the squared chord length. Note that the // argument is automatically clamped to a maximum of 4.0 to handle possible // roundoff errors. The argument must be non-negative. static constexpr S1ChordAngle FromLength2(double length2); // Converts to an S1Angle. Can be used just like an S1Angle constructor: // // S1ChordAngle x = ...; // return S1Angle(x); // // Infinity() is converted to S1Angle::Infinity(), and Negative() is // converted to an unspecified negative S1Angle. // // Note that the conversion uses trigonometric functions and therefore // should be avoided in inner loops. explicit operator S1Angle() const; // Converts to an S1Angle (equivalent to the operator above). S1Angle ToAngle() const; // Convenience methods implemented by calling ToAngle() first. Note that // because of the S1Angle conversion these methods are relatively expensive // (despite their lowercase names), so the results should be cached if they // are needed inside loops. double radians() const; double degrees() const; int32_t e5() const; int32_t e6() const; int32_t e7() const; // All operators and functions are declared here so that we can put them all // in one place. (The compound assignment operators must be put here.) #ifndef SWIG // `friend operator`s are incompatible with SWIG 4.0, but work with 4.3. // Comparison operators. friend constexpr bool operator==(S1ChordAngle x, S1ChordAngle y); #if defined(__cpp_impl_three_way_comparison) && \ __cpp_impl_three_way_comparison >= 201907L // This should be `= default`, but can't be due to PyCLIF limitations. // NOLINTNEXTLINE(clang-diagnostic-pre-c++20-compat) friend constexpr auto operator<=>(S1ChordAngle x, S1ChordAngle y) { // NOLINTNEXTLINE(clang-diagnostic-pre-c++20-compat) return x.length2() <=> y.length2(); } #else friend constexpr bool operator!=(S1ChordAngle x, S1ChordAngle y) { return x.length2() != y.length2(); } friend constexpr bool operator<(S1ChordAngle x, S1ChordAngle y) { return x.length2() < y.length2(); } friend constexpr bool operator>(S1ChordAngle x, S1ChordAngle y) { return x.length2() > y.length2(); } friend constexpr bool operator<=(S1ChordAngle x, S1ChordAngle y) { return x.length2() <= y.length2(); } friend constexpr bool operator>=(S1ChordAngle x, S1ChordAngle y) { return x.length2() >= y.length2(); } #endif #endif // !SWIG // Comparison predicates. constexpr bool is_zero() const; constexpr bool is_negative() const; constexpr bool is_infinity() const; constexpr bool is_special() const; // Negative or infinity. // Only addition and subtraction of S1ChordAngles is supported. These // methods add or subtract the corresponding S1Angles, and clamp the result // to the range [0, Pi]. Both arguments must be non-negative and // non-infinite. // // REQUIRES: !a.is_special() && !b.is_special() friend S1ChordAngle operator+(S1ChordAngle a, S1ChordAngle b); friend S1ChordAngle operator-(S1ChordAngle a, S1ChordAngle b); S1ChordAngle& operator+=(S1ChordAngle a); S1ChordAngle& operator-=(S1ChordAngle a); // Trigonmetric functions. It is more accurate and efficient to call these // rather than first converting to an S1Angle. friend double sin(S1ChordAngle a); friend double cos(S1ChordAngle a); friend double tan(S1ChordAngle a); // Returns sin(a)**2, but computed more efficiently. friend double sin2(S1ChordAngle a); // The squared length of the chord. (Most clients will not need this.) constexpr double length2() const { return length2_; } // Returns the smallest representable S1ChordAngle larger than this object. // This can be used to convert a "<" comparison to a "<=" comparison. For // example: // // S2ClosestEdgeQuery query(...); // S1ChordAngle limit = ...; // if (query.IsDistanceLess(target, limit.Successor())) { // // Distance to "target" is less than or equal to "limit". // } // // Note the following special cases: // Negative().Successor() == Zero() // Straight().Successor() == Infinity() // Infinity().Successor() == Infinity() S1ChordAngle Successor() const; // Like Successor(), but returns the largest representable S1ChordAngle less // than this object. // // Note the following special cases: // Infinity().Predecessor() == Straight() // Zero().Predecessor() == Negative() // Negative().Predecessor() == Negative() S1ChordAngle Predecessor() const; // Returns a new S1ChordAngle that has been adjusted by the given error // bound (which can be positive or negative). "error" should be the value // returned by one of the error bound methods below. For example: // S1ChordAngle a(x, y); // S1ChordAngle a1 = a.PlusError(a.GetS2PointConstructorMaxError()); S1ChordAngle PlusError(double error) const; // Return the maximum error in length2() for the S1ChordAngle(x, y) // constructor, assuming that "x" and "y" are normalized to within the // bounds guaranteed by S2Point::Normalize(). (The error is defined with // respect to the true distance after the points are projected to lie // exactly on the sphere.) double GetS2PointConstructorMaxError() const; // Return the maximum error in length2() for the S1Angle constructor. double GetS1AngleConstructorMaxError() const; // Return true if the internal representation is valid. Negative() and // Infinity() are both considered valid. constexpr bool is_valid() const; // When S1ChordAngle is used as a key in one of the absl::btree container // types, indicate that linear rather than binary search should be used. // This is much faster when the comparison function is cheap. typedef std::true_type absl_btree_prefer_linear_node_search; private: // S1ChordAngles are represented by the squared chord length, which can // range from 0 to 4. Infinity() uses an infinite squared length. explicit constexpr S1ChordAngle(double length2) : length2_(length2) { ABSL_DCHECK(is_valid()); } double length2_ = 0.0; }; ////////////////// Implementation details follow //////////////////// inline S1ChordAngle::S1ChordAngle(S1Angle angle) { if (angle.radians() < 0) { *this = Negative(); } else if (angle == S1Angle::Infinity()) { *this = Infinity(); } else { // The chord length is 2 * sin(angle / 2). double length = 2 * sin(0.5 * std::min(M_PI, angle.radians())); length2_ = length * length; } ABSL_DCHECK(is_valid()); } inline S1ChordAngle::S1ChordAngle(const S2Point& x, const S2Point& y) : length2_(std::min(4.0, (x - y).Norm2())) { ABSL_DCHECK(S2::IsUnitLength(x)); ABSL_DCHECK(S2::IsUnitLength(y)); // The squared distance may slightly exceed 4.0 due to roundoff errors. // The maximum error in the result is 2 * DBL_EPSILON * length2_. ABSL_DCHECK(is_valid()); } inline constexpr bool S1ChordAngle::is_valid() const { return (length2_ >= 0 && length2_ <= 4.0) || is_special(); } inline constexpr S1ChordAngle S1ChordAngle::FromLength2(double length2) { return S1ChordAngle(std::min(4.0, length2)); } inline constexpr S1ChordAngle S1ChordAngle::Zero() { return S1ChordAngle(0); } inline constexpr S1ChordAngle S1ChordAngle::Right() { return S1ChordAngle(2); } inline constexpr S1ChordAngle S1ChordAngle::Straight() { return S1ChordAngle(4); } inline constexpr S1ChordAngle S1ChordAngle::Infinity() { return S1ChordAngle(std::numeric_limits::infinity()); } inline constexpr S1ChordAngle S1ChordAngle::Negative() { return S1ChordAngle(-1); } inline S1ChordAngle S1ChordAngle::Radians(double radians) { return S1ChordAngle(S1Angle::Radians(radians)); } inline S1ChordAngle S1ChordAngle::Degrees(double degrees) { return S1ChordAngle(S1Angle::Degrees(degrees)); } inline S1ChordAngle S1ChordAngle::E5(int32_t e5) { return S1ChordAngle(S1Angle::E5(e5)); } inline S1ChordAngle S1ChordAngle::E6(int32_t e6) { return S1ChordAngle(S1Angle::E6(e6)); } inline S1ChordAngle S1ChordAngle::E7(int32_t e7) { return S1ChordAngle(S1Angle::E7(e7)); } inline constexpr S1ChordAngle S1ChordAngle::FastUpperBoundFrom(S1Angle angle) { // This method uses the distance along the surface of the sphere as an upper // bound on the distance through the sphere's interior. return S1ChordAngle::FromLength2(angle.radians() * angle.radians()); } inline S1ChordAngle::operator S1Angle() const { return ToAngle(); } inline double S1ChordAngle::radians() const { return ToAngle().radians(); } inline double S1ChordAngle::degrees() const { return ToAngle().degrees(); } inline int32_t S1ChordAngle::e5() const { return ToAngle().e5(); } inline int32_t S1ChordAngle::e6() const { return ToAngle().e6(); } inline int32_t S1ChordAngle::e7() const { return ToAngle().e7(); } inline constexpr bool S1ChordAngle::is_zero() const { return length2_ == 0; } inline constexpr bool S1ChordAngle::is_negative() const { // TODO(ericv): Consider stricter check here -- only allow Negative(). return length2_ < 0; } inline constexpr bool S1ChordAngle::is_infinity() const { return length2_ == std::numeric_limits::infinity(); } inline constexpr bool S1ChordAngle::is_special() const { return is_negative() || is_infinity(); } inline constexpr bool operator==(S1ChordAngle x, S1ChordAngle y) { return x.length2() == y.length2(); } inline S1ChordAngle& S1ChordAngle::operator+=(S1ChordAngle a) { return (*this = *this + a); } inline S1ChordAngle& S1ChordAngle::operator-=(S1ChordAngle a) { return (*this = *this - a); } // Outputs the chord angle as the equivalent S1Angle. std::ostream& operator<<(std::ostream& os, S1ChordAngle a); #endif // S2_S1CHORD_ANGLE_H_ src/s2/s1chord_angle_test.cc000066400000000000000000000256521524103652300162630ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/s1chord_angle.h" #include #include #include #include #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "s2/s1angle.h" #include "s2/s2edge_distances.h" #include "s2/s2point.h" #include "s2/s2predicates.h" #include "s2/s2random.h" #include "s2/s2testing.h" #include "s2/util/math/matrix3x3.h" using std::numeric_limits; TEST(S1ChordAngle, ConstexprFunctionsWork) { // Test constexpr constructors. static constexpr auto kTestZero = S1ChordAngle::Zero(); static constexpr auto kTestRight = S1ChordAngle::Right(); static constexpr auto kTestStraight = S1ChordAngle::Straight(); static constexpr auto kTestInfinity = S1ChordAngle::Infinity(); static constexpr auto kTestNegative = S1ChordAngle::Negative(); static constexpr auto kTestFastUpperBound = S1ChordAngle::FastUpperBoundFrom(S1Angle::Radians(1)); static constexpr auto kTestFromLength2 = S1ChordAngle::FromLength2(2); EXPECT_EQ(kTestRight, S1ChordAngle::Right()); EXPECT_EQ(kTestStraight, S1ChordAngle::Straight()); EXPECT_EQ(kTestFromLength2.length2(), 2); constexpr bool kIsZero = kTestZero.is_zero(); EXPECT_TRUE(kIsZero); constexpr bool kIsNegative = kTestNegative.is_negative(); EXPECT_TRUE(kIsNegative); constexpr bool kIsInfinity = kTestInfinity.is_infinity(); EXPECT_TRUE(kIsInfinity); constexpr bool kIsSpecial = kTestNegative.is_special(); EXPECT_TRUE(kIsSpecial); constexpr bool kIsValid = kTestFastUpperBound.is_valid(); EXPECT_TRUE(kIsValid); } TEST(S1ChordAngle, DefaultConstructor) { // Check that the default constructor returns an angle of 0. S1ChordAngle a; EXPECT_EQ(S1ChordAngle::Zero(), a); } TEST(S1ChordAngle, TwoPointConstructor) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "TWO_POINT_CONSTRUCTOR", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); for (int iter = 0; iter < 100; ++iter) { S2Point x, y, z; s2random::Frame(bitgen, x, y, z); EXPECT_EQ(S1Angle::Zero(), S1Angle(S1ChordAngle(z, z))); EXPECT_NEAR(M_PI, S1ChordAngle(-z, z).radians(), 1e-7); EXPECT_DOUBLE_EQ(M_PI_2, S1ChordAngle(x, z).radians()); S2Point w = (y + z).Normalize(); EXPECT_DOUBLE_EQ(M_PI_4, S1ChordAngle(w, z).radians()); } } TEST(S1ChordAngle, FromLength2) { EXPECT_EQ(0, S1ChordAngle::FromLength2(0).degrees()); EXPECT_DOUBLE_EQ(60, S1ChordAngle::FromLength2(1).degrees()); EXPECT_DOUBLE_EQ(90, S1ChordAngle::FromLength2(2).degrees()); EXPECT_EQ(180, S1ChordAngle::FromLength2(4).degrees()); EXPECT_EQ(180, S1ChordAngle::FromLength2(5).degrees()); } TEST(S1ChordAngle, Zero) { EXPECT_EQ(S1Angle::Zero(), S1Angle(S1ChordAngle::Zero())); } TEST(S1ChordAngle, Right) { EXPECT_DOUBLE_EQ(90, S1ChordAngle::Right().degrees()); } TEST(S1ChordAngle, Straight) { EXPECT_EQ(S1Angle::Degrees(180), S1Angle(S1ChordAngle::Straight())); } TEST(S1ChordAngle, Infinity) { EXPECT_LT(S1ChordAngle::Straight(), S1ChordAngle::Infinity()); EXPECT_EQ(S1ChordAngle::Infinity(), S1ChordAngle::Infinity()); EXPECT_EQ(S1Angle::Infinity(), S1Angle(S1ChordAngle::Infinity())); } TEST(S1ChordAngle, Negative) { EXPECT_LT(S1ChordAngle::Negative(), S1ChordAngle::Zero()); EXPECT_EQ(S1ChordAngle::Negative(), S1ChordAngle::Negative()); EXPECT_LT(S1ChordAngle::Negative().ToAngle(), S1Angle::Zero()); } TEST(S1ChordAngle, Predicates) { EXPECT_TRUE(S1ChordAngle::Zero().is_zero()); EXPECT_FALSE(S1ChordAngle::Zero().is_negative()); EXPECT_FALSE(S1ChordAngle::Zero().is_special()); EXPECT_FALSE(S1ChordAngle::Straight().is_special()); EXPECT_TRUE(S1ChordAngle::Negative().is_negative()); EXPECT_TRUE(S1ChordAngle::Negative().is_special()); EXPECT_TRUE(S1ChordAngle::Infinity().is_infinity()); EXPECT_TRUE(S1ChordAngle::Infinity().is_special()); } TEST(S1ChordAngle, ToFromS1Angle) { EXPECT_EQ(0, S1ChordAngle(S1Angle::Zero()).radians()); EXPECT_EQ(4, S1ChordAngle(S1Angle::Radians(M_PI)).length2()); EXPECT_EQ(M_PI, S1ChordAngle(S1Angle::Radians(M_PI)).radians()); EXPECT_EQ(S1Angle::Infinity(), S1Angle(S1ChordAngle(S1Angle::Infinity()))); EXPECT_LT(S1ChordAngle(S1Angle::Radians(-1)).radians(), 0); EXPECT_DOUBLE_EQ(1.0, S1ChordAngle(S1Angle::Radians(1.0)).radians()); } TEST(S1ChordAngle, Successor) { EXPECT_EQ(S1ChordAngle::Zero(), S1ChordAngle::Negative().Successor()); EXPECT_EQ(S1ChordAngle::Infinity(), S1ChordAngle::Straight().Successor()); EXPECT_EQ(S1ChordAngle::Infinity(), S1ChordAngle::Infinity().Successor()); S1ChordAngle x = S1ChordAngle::Negative(); for (int i = 0; i < 10; ++i) { EXPECT_LT(x, x.Successor()); x = x.Successor(); } } TEST(S1ChordAngle, Predecessor) { EXPECT_EQ(S1ChordAngle::Straight(), S1ChordAngle::Infinity().Predecessor()); EXPECT_EQ(S1ChordAngle::Negative(), S1ChordAngle::Zero().Predecessor()); EXPECT_EQ(S1ChordAngle::Negative(), S1ChordAngle::Negative().Predecessor()); S1ChordAngle x = S1ChordAngle::Infinity(); for (int i = 0; i < 10; ++i) { EXPECT_GT(x, x.Predecessor()); x = x.Predecessor(); } } TEST(S1ChordAngle, Arithmetic) { S1ChordAngle zero = S1ChordAngle::Zero(); S1ChordAngle degree30 = S1ChordAngle::Degrees(30); S1ChordAngle degree60 = S1ChordAngle::Degrees(60); S1ChordAngle degree90 = S1ChordAngle::Degrees(90); S1ChordAngle degree120 = S1ChordAngle::Degrees(120); S1ChordAngle degree180 = S1ChordAngle::Straight(); EXPECT_EQ(0, (zero + zero).degrees()); EXPECT_EQ(0, (zero - zero).degrees()); EXPECT_EQ(0, (degree60 - degree60).degrees()); EXPECT_EQ(0, (degree180 - degree180).degrees()); EXPECT_EQ(0, (zero - degree60).degrees()); EXPECT_EQ(0, (degree30 - degree90).degrees()); // `EXPECT_DOUBLE_EQ` compares with 4 ULP tolerance. EXPECT_DOUBLE_EQ(60, (degree60 + zero).degrees()); EXPECT_DOUBLE_EQ(60, (degree60 - zero).degrees()); EXPECT_DOUBLE_EQ(60, (zero + degree60).degrees()); EXPECT_DOUBLE_EQ(90, (degree30 + degree60).degrees()); EXPECT_DOUBLE_EQ(90, (degree60 + degree30).degrees()); EXPECT_DOUBLE_EQ(60, (degree90 - degree30).degrees()); #ifndef _WIN32 EXPECT_DOUBLE_EQ(30, (degree90 - degree60).degrees()); #else // TODO(b/387870507): Figure out if this is a bug or the tolerance is // wrong. EXPECT_DOUBLE_EQ(30.000000000000018, (degree90 - degree60).degrees()); #endif // defined(_WIN32) EXPECT_EQ(180, (degree180 + zero).degrees()); EXPECT_EQ(180, (degree180 - zero).degrees()); EXPECT_EQ(180, (degree90 + degree90).degrees()); EXPECT_EQ(180, (degree120 + degree90).degrees()); EXPECT_EQ(180, (degree120 + degree120).degrees()); EXPECT_EQ(180, (degree30 + degree180).degrees()); EXPECT_EQ(180, (degree180 + degree180).degrees()); } TEST(S1ChordAngle, ArithmeticPrecision) { // Verifies that S1ChordAngle is capable of adding and subtracting angles // extremely accurately up to Pi/2 radians. (Accuracy continues to be good // well beyond this value but degrades as angles approach Pi.) S1ChordAngle kEps = S1ChordAngle::Radians(1e-15); S1ChordAngle k90 = S1ChordAngle::Right(); S1ChordAngle k90MinusEps = k90 - kEps; S1ChordAngle k90PlusEps = k90 + kEps; double kMaxError = 2 * DBL_EPSILON; EXPECT_NEAR(k90MinusEps.radians(), M_PI_2 - kEps.radians(), kMaxError); EXPECT_NEAR(k90PlusEps.radians(), M_PI_2 + kEps.radians(), kMaxError); EXPECT_NEAR((k90 - k90MinusEps).radians(), kEps.radians(), kMaxError); EXPECT_NEAR((k90PlusEps - k90).radians(), kEps.radians(), kMaxError); EXPECT_NEAR((k90MinusEps + kEps).radians(), M_PI_2, kMaxError); } TEST(S1ChordAngle, Trigonometry) { static constexpr int kIters = 20; for (int iter = 0; iter <= kIters; ++iter) { double radians = M_PI * iter / kIters; S1ChordAngle angle(S1Angle::Radians(radians)); EXPECT_NEAR(sin(radians), sin(angle), 1e-15) << radians; EXPECT_NEAR(cos(radians), cos(angle), 1e-15) << radians; // Since the tan(x) is unbounded near Pi/4, we map the result back to an // angle before comparing. (The assertion is that the result is equal to // the tangent of a nearby angle.) #ifndef _WIN32 EXPECT_NEAR(atan(tan(radians)), atan(tan(angle)), 1e-15) << radians; #else // TODO(b/387870507): On Windows, we get -pi/2 (instead of pi/2) for an // input of pi/2. Figure out why this is happening. if (iter == kIters / 2) { EXPECT_NEAR(-M_PI_2, atan(tan(angle)), 1e-15) << radians; } else { EXPECT_NEAR(atan(tan(radians)), atan(tan(angle)), 1e-15) << radians; } #endif // defined(_WIN32) } // Unlike S1Angle, S1ChordAngle can represent 90 and 180 degrees exactly. S1ChordAngle angle90 = S1ChordAngle::FromLength2(2); S1ChordAngle angle180 = S1ChordAngle::FromLength2(4); EXPECT_EQ(1, sin(angle90)); EXPECT_EQ(0, cos(angle90)); EXPECT_EQ(numeric_limits::infinity(), tan(angle90)); EXPECT_EQ(0, sin(angle180)); EXPECT_EQ(-1, cos(angle180)); EXPECT_EQ(0, tan(angle180)); } TEST(S1ChordAngle, PlusError) { EXPECT_EQ(S1ChordAngle::Negative(), S1ChordAngle::Negative().PlusError(5)); EXPECT_EQ(S1ChordAngle::Infinity(), S1ChordAngle::Infinity().PlusError(-5)); EXPECT_EQ(S1ChordAngle::Straight(), S1ChordAngle::Straight().PlusError(5)); EXPECT_EQ(S1ChordAngle::Zero(), S1ChordAngle::Zero().PlusError(-5)); EXPECT_EQ(S1ChordAngle::FromLength2(1.25), S1ChordAngle::FromLength2(1).PlusError(0.25)); EXPECT_EQ(S1ChordAngle::FromLength2(0.75), S1ChordAngle::FromLength2(1).PlusError(-0.25)); } TEST(S1ChordAngle, GetS2PointConstructorMaxError) { // Check that the error bound returned by GetS2PointConstructorMaxError() is // large enough. absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "GET_S2_POINT_CONSTRUCTOR_MAX_ERROR", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); for (int iter = 0; iter < 100000; ++iter) { S2Point x = s2random::Point(bitgen); S2Point y = s2random::Point(bitgen); if (absl::Bernoulli(bitgen, 0.1)) { // Occasionally test a point pair that is nearly identical or antipodal. S1Angle r = S1Angle::Radians(1e-15 * absl::Uniform(bitgen, 0.0, 1.0)); y = S2::GetPointOnLine(x, y, r); if (absl::Bernoulli(bitgen, 0.5)) y = -y; } S1ChordAngle dist = S1ChordAngle(x, y); double error = dist.GetS2PointConstructorMaxError(); EXPECT_LE(s2pred::CompareDistance(x, y, dist.PlusError(error)), 0) << "angle=" << S1Angle(dist) << ", iter=" << iter; EXPECT_GE(s2pred::CompareDistance(x, y, dist.PlusError(-error)), 0) << "angle=" << S1Angle(dist) << ", iter=" << iter; } } src/s2/s1interval.cc000066400000000000000000000240651524103652300146000ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s1interval.h" #include #include #include #include "absl/log/absl_check.h" using std::fabs; using std::max; S1Interval S1Interval::FromPoint(double p) { if (p == -M_PI) p = M_PI; return S1Interval(p, p, ARGS_CHECKED); } double S1Interval::GetCenter() const { double center = 0.5 * (lo() + hi()); if (!is_inverted()) return center; // Return the center in the range (-Pi, Pi]. return (center <= 0) ? (center + M_PI) : (center - M_PI); } double S1Interval::GetLength() const { double length = hi() - lo(); if (length >= 0) return length; length += 2 * M_PI; // Empty intervals have a negative length. return (length > 0) ? length : -1; } S1Interval S1Interval::Complement() const { if (lo() == hi()) return Full(); // Singleton. return S1Interval(hi(), lo(), ARGS_CHECKED); // Handles empty and full. } double S1Interval::GetComplementCenter() const { if (lo() != hi()) { return Complement().GetCenter(); } else { // Singleton. return (hi() <= 0) ? (hi() + M_PI) : (hi() - M_PI); } } bool S1Interval::FastContains(double p) const { if (is_inverted()) { return (p >= lo() || p <= hi()) && !is_empty(); } else { return p >= lo() && p <= hi(); } } bool S1Interval::Contains(double p) const { // Works for empty, full, and singleton intervals. ABSL_DCHECK(IsValidPoint(p)) << p; if (p == -M_PI) p = M_PI; return FastContains(p); } bool S1Interval::InteriorContains(double p) const { // Works for empty, full, and singleton intervals. ABSL_DCHECK(IsValidPoint(p)) << p; if (p == -M_PI) p = M_PI; if (is_inverted()) { return p > lo() || p < hi(); } else { return (p > lo() && p < hi()) || is_full(); } } bool S1Interval::Contains(const S1Interval& y) const { // It might be helpful to compare the structure of these tests to // the simpler Contains(double) method above. if (is_inverted()) { if (y.is_inverted()) return y.lo() >= lo() && y.hi() <= hi(); return (y.lo() >= lo() || y.hi() <= hi()) && !is_empty(); } else { if (y.is_inverted()) return is_full() || y.is_empty(); return y.lo() >= lo() && y.hi() <= hi(); } } bool S1Interval::InteriorContains(const S1Interval& y) const { if (is_inverted()) { if (!y.is_inverted()) return y.lo() > lo() || y.hi() < hi(); return (y.lo() > lo() && y.hi() < hi()) || y.is_empty(); } else { if (y.is_inverted()) return is_full() || y.is_empty(); return (y.lo() > lo() && y.hi() < hi()) || is_full(); } } bool S1Interval::Intersects(const S1Interval& y) const { if (is_empty() || y.is_empty()) return false; if (is_inverted()) { // Every non-empty inverted interval contains Pi. return y.is_inverted() || y.lo() <= hi() || y.hi() >= lo(); } else { if (y.is_inverted()) return y.lo() <= hi() || y.hi() >= lo(); return y.lo() <= hi() && y.hi() >= lo(); } } bool S1Interval::InteriorIntersects(const S1Interval& y) const { if (is_empty() || y.is_empty() || lo() == hi()) return false; if (is_inverted()) { return y.is_inverted() || y.lo() < hi() || y.hi() > lo(); } else { if (y.is_inverted()) return y.lo() < hi() || y.hi() > lo(); return (y.lo() < hi() && y.hi() > lo()) || is_full(); } } inline static double PositiveDistance(double a, double b) { // Compute the distance from "a" to "b" in the range [0, 2*Pi). // This is equivalent to (remainder(b - a - M_PI, 2 * M_PI) + M_PI), // except that it is more numerically stable (it does not lose // precision for very small positive distances). double d = b - a; if (d >= 0) return d; // We want to ensure that if b == Pi and a == (-Pi + eps), // the return result is approximately 2*Pi and not zero. return (b + M_PI) - (a - M_PI); } double S1Interval::GetDirectedHausdorffDistance(const S1Interval& y) const { if (y.Contains(*this)) return 0.0; // this includes the case *this is empty if (y.is_empty()) return M_PI; // maximum possible distance on S1 double y_complement_center = y.GetComplementCenter(); if (Contains(y_complement_center)) { return PositiveDistance(y.hi(), y_complement_center); } else { // The Hausdorff distance is realized by either two hi() endpoints or two // lo() endpoints, whichever is farther apart. double hi_hi = S1Interval(y.hi(), y_complement_center).Contains(hi()) ? PositiveDistance(y.hi(), hi()) : 0; double lo_lo = S1Interval(y_complement_center, y.lo()).Contains(lo()) ? PositiveDistance(lo(), y.lo()) : 0; ABSL_DCHECK(hi_hi > 0 || lo_lo > 0); return max(hi_hi, lo_lo); } } void S1Interval::AddPoint(double p) { ABSL_DCHECK(IsValidPoint(p)) << p; if (p == -M_PI) p = M_PI; if (FastContains(p)) return; if (is_empty()) { set_hi(p); set_lo(p); } else { // Compute distance from p to each endpoint. double dlo = PositiveDistance(p, lo()); double dhi = PositiveDistance(hi(), p); if (dlo < dhi) { set_lo(p); } else { set_hi(p); } // Adding a point can never turn a non-full interval into a full one. } } double S1Interval::Project(double p) const { ABSL_DCHECK(!is_empty()); ABSL_DCHECK(IsValidPoint(p)) << p; if (p == -M_PI) p = M_PI; if (FastContains(p)) return p; // Compute distance from p to each endpoint. double dlo = PositiveDistance(p, lo()); double dhi = PositiveDistance(hi(), p); return (dlo < dhi) ? lo() : hi(); } S1Interval S1Interval::FromPointPair(double p1, double p2) { ABSL_DCHECK(IsValidPoint(p1)) << p1; ABSL_DCHECK(IsValidPoint(p2)) << p2; if (p1 == -M_PI) p1 = M_PI; if (p2 == -M_PI) p2 = M_PI; if (PositiveDistance(p1, p2) <= M_PI) { return S1Interval(p1, p2, ARGS_CHECKED); } else { return S1Interval(p2, p1, ARGS_CHECKED); } } S1Interval S1Interval::Expanded(double margin) const { if (margin >= 0) { if (is_empty()) return *this; // Check whether this interval will be full after expansion, allowing // for a 1-bit rounding error when computing each endpoint. if (GetLength() + 2 * margin + 2 * DBL_EPSILON >= 2 * M_PI) return Full(); } else { if (is_full()) return *this; // Check whether this interval will be empty after expansion, allowing // for a 1-bit rounding error when computing each endpoint. if (GetLength() + 2 * margin - 2 * DBL_EPSILON <= 0) return Empty(); } S1Interval result(remainder(lo() - margin, 2*M_PI), remainder(hi() + margin, 2*M_PI)); if (result.lo() <= -M_PI) result.set_lo(M_PI); return result; } S1Interval S1Interval::Union(const S1Interval& y) const { // The y.is_full() case is handled correctly in all cases by the code // below, but can follow three separate code paths depending on whether // this interval is inverted, is non-inverted but contains Pi, or neither. if (y.is_empty()) return *this; if (FastContains(y.lo())) { if (FastContains(y.hi())) { // Either this interval contains y, or the union of the two // intervals is the Full() interval. if (Contains(y)) return *this; // is_full() code path return Full(); } return S1Interval(lo(), y.hi(), ARGS_CHECKED); } if (FastContains(y.hi())) return S1Interval(y.lo(), hi(), ARGS_CHECKED); // This interval contains neither endpoint of y. This means that either y // contains all of this interval, or the two intervals are disjoint. if (is_empty() || y.FastContains(lo())) return y; // Check which pair of endpoints are closer together. double dlo = PositiveDistance(y.hi(), lo()); double dhi = PositiveDistance(hi(), y.lo()); if (dlo < dhi) { return S1Interval(y.lo(), hi(), ARGS_CHECKED); } else { return S1Interval(lo(), y.hi(), ARGS_CHECKED); } } S1Interval S1Interval::Intersection(const S1Interval& y) const { // The y.is_full() case is handled correctly in all cases by the code // below, but can follow three separate code paths depending on whether // this interval is inverted, is non-inverted but contains Pi, or neither. if (y.is_empty()) return Empty(); if (FastContains(y.lo())) { if (FastContains(y.hi())) { // Either this interval contains y, or the region of intersection // consists of two disjoint subintervals. In either case, we want // to return the shorter of the two original intervals. if (y.GetLength() < GetLength()) return y; // is_full() code path return *this; } return S1Interval(y.lo(), hi(), ARGS_CHECKED); } if (FastContains(y.hi())) return S1Interval(lo(), y.hi(), ARGS_CHECKED); // This interval contains neither endpoint of y. This means that either y // contains all of this interval, or the two intervals are disjoint. if (y.FastContains(lo())) return *this; // is_empty() okay here ABSL_DCHECK(!Intersects(y)); return Empty(); } bool S1Interval::ApproxEquals(const S1Interval& y, double max_error) const { // Full and empty intervals require special cases because the "endpoints" // are considered to be positioned arbitrarily. if (is_empty()) return y.GetLength() <= 2 * max_error; if (y.is_empty()) return GetLength() <= 2 * max_error; if (is_full()) return y.GetLength() >= 2 * (M_PI - max_error); if (y.is_full()) return GetLength() >= 2 * (M_PI - max_error); // The purpose of the last test below is to verify that moving the endpoints // does not invert the interval, e.g. [-1e20, 1e20] vs. [1e20, -1e20]. return (fabs(remainder(y.lo() - lo(), 2 * M_PI)) <= max_error && fabs(remainder(y.hi() - hi(), 2 * M_PI)) <= max_error && fabs(GetLength() - y.GetLength()) <= 2 * max_error); } src/s2/s1interval.h000066400000000000000000000261201524103652300144340ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_S1INTERVAL_H_ #define S2_S1INTERVAL_H_ #include #include #include #include #include "absl/hash/hash.h" #include "absl/log/absl_check.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/util/math/vector.h" // IWYU pragma: export // An S1Interval represents a closed interval on a unit circle (also known // as a 1-dimensional sphere). It is capable of representing the empty // interval (containing no points), the full interval (containing all // points), and zero-length intervals (containing a single point). // // Points are represented by the angle they make with the positive x-axis in // the range [-Pi, Pi]. An interval is represented by its lower and upper // bounds (both inclusive, since the interval is closed). The lower bound may // be greater than the upper bound, in which case the interval is "inverted" // (i.e. it passes through the point (-1, 0)). // // Note that the point (-1, 0) has two valid representations, Pi and -Pi. // The normalized representation of this point internally is Pi, so that // endpoints of normal intervals are in the range (-Pi, Pi]. However, we // take advantage of the point -Pi to construct two special intervals: // the Full() interval is [-Pi, Pi], and the Empty() interval is [Pi, -Pi]. // // This class is intended to be copied by value as desired. It uses // the default copy constructor and assignment operator. class S1Interval { public: // Constructor. Both endpoints must be in the range -Pi to Pi inclusive. // The value -Pi is converted internally to Pi except for the Full() // and Empty() intervals. S1Interval(double lo, double hi); // The default constructor creates an empty interval. // // Note: Don't construct an interval using the default constructor and // set_lo()/set_hi(). If you need to set both endpoints, use the // constructor above: // // lng_bounds_ = S1Interval(lng_lo, lng_hi); S1Interval(); // Returns the empty interval. static S1Interval Empty(); // Returns the full interval. static S1Interval Full(); // Convenience method to construct an interval containing a single point. static S1Interval FromPoint(double p); // Convenience method to construct the minimal interval containing // the two given points. This is equivalent to starting with an empty // interval and calling AddPoint() twice, but it is more efficient. static S1Interval FromPointPair(double p1, double p2); // Accessors methods. double lo() const { return bounds_[0]; } double hi() const { return bounds_[1]; } // Methods that allow the S1Interval to be accessed as a vector. (The // recommended style is to use lo() and hi() whenever possible, but these // methods are useful when the endpoint to be selected is not constant.) // // Only const versions of these methods are provided, since S1Interval // has invariants that must be maintained after each update. double operator[](int i) const { return bounds_[i]; } const Vector2_d& bounds() const { return bounds_; } // An interval is valid if neither bound exceeds Pi in absolute value, // and the value -Pi appears only in the Empty() and Full() intervals. bool is_valid() const; // Return true if the interval contains all points on the unit circle. bool is_full() const { return lo() == -M_PI && hi() == M_PI; } // Return true if the interval is empty, i.e. it contains no points. bool is_empty() const { return lo() == M_PI && hi() == -M_PI; } // Return true if lo() > hi(). (This is true for empty intervals.) bool is_inverted() const { return lo() > hi(); } // Return the midpoint of the interval. For full and empty intervals, // the result is arbitrary. double GetCenter() const; // Return the length of the interval. The length of an empty interval // is negative. double GetLength() const; // Return the complement of the interior of the interval. An interval and // its complement have the same boundary but do not share any interior // values. The complement operator is not a bijection, since the complement // of a singleton interval (containing a single value) is the same as the // complement of an empty interval. S1Interval Complement() const; // Return the midpoint of the complement of the interval. For full and empty // intervals, the result is arbitrary. For a singleton interval (containing a // single point), the result is its antipodal point on S1. double GetComplementCenter() const; // Return true if the interval (which is closed) contains the point 'p'. bool Contains(double p) const; // Return true if the interior of the interval contains the point 'p'. bool InteriorContains(double p) const; // Return true if the interval contains the given interval 'y'. // Works for empty, full, and singleton intervals. bool Contains(const S1Interval& y) const; // Returns true if the interior of this interval contains the entire // interval 'y'. Note that x.InteriorContains(x) is true only when // x is the empty or full interval, and x.InteriorContains(S1Interval(p,p)) // is equivalent to x.InteriorContains(p). bool InteriorContains(const S1Interval& y) const; // Return true if the two intervals contain any points in common. // Note that the point +/-Pi has two representations, so the intervals // [-Pi,-3] and [2,Pi] intersect, for example. bool Intersects(const S1Interval& y) const; // Return true if the interior of this interval contains any point of the // interval 'y' (including its boundary). Works for empty, full, and // singleton intervals. bool InteriorIntersects(const S1Interval& y) const; // Return the Hausdorff distance to the given interval 'y'. For two // S1Intervals x and y, this distance is defined by // h(x, y) = max_{p in x} min_{q in y} d(p, q), // where d(.,.) is measured along S1. double GetDirectedHausdorffDistance(const S1Interval& y) const; // Expand the interval by the minimum amount necessary so that it // contains the given point "p" (an angle in the range [-Pi, Pi]). void AddPoint(double p); // Return the closest point in the interval to the given point "p". // The interval must be non-empty. double Project(double p) const; // Return an interval that has been expanded on each side by the given // distance "margin". If "margin" is negative, then shrink the interval on // each side by "margin" instead. The resulting interval may be empty or // full. Any expansion (positive or negative) of a full interval remains // full, and any expansion of an empty interval remains empty. S1Interval Expanded(double margin) const; // Return the smallest interval that contains this interval and the // given interval "y". S1Interval Union(const S1Interval& y) const; // Return the smallest interval that contains the intersection of this // interval with "y". Note that the region of intersection may // consist of two disjoint intervals. S1Interval Intersection(const S1Interval& y) const; // Return true if two intervals contains the same set of points. bool operator==(const S1Interval& y) const; // Return true if two intervals do not contain the same set of points. bool operator!=(const S1Interval& y) const; // Return true if this interval can be transformed into the given interval by // moving each endpoint by at most "max_error" (and without the endpoints // crossing, which would invert the interval). Empty and full intervals are // considered to start at an arbitrary point on the unit circle, thus any // interval with (length <= 2*max_error) matches the empty interval, and any // interval with (length >= 2*Pi - 2*max_error) matches the full interval. // Note: default value is duplicated in Python bindings (s1interval_bindings.cc) bool ApproxEquals(const S1Interval& y, double max_error = 1e-15) const; // Low-level methods to modify one endpoint of an existing S1Interval. // These methods should really be private because setting just one endpoint // can violate the invariants maintained by S1Interval. In particular: // // - It is not valid to call these methods on an Empty() or Full() // interval, since these intervals do not have any endpoints. // // - It is not allowed to set an endpoint to -Pi. (When these methods are // used internally, values of -Pi have already been normalized to Pi.) // // The preferred way to modify both endpoints of an interval is to use a // constructor, e.g. lng = S1Interval(lng_lo, lng_hi). void set_lo(double p); void set_hi(double p); // Returns true if the given value is a valid S1 point, i.e. it is // in the range [-Pi, Pi]. static bool IsValidPoint(double p) { return std::fabs(p) <= M_PI; } private: enum ArgsChecked { ARGS_CHECKED }; // Internal constructor that assumes that both arguments are in the // correct range, i.e. normalization from -Pi to Pi is already done. S1Interval(double lo, double hi, ArgsChecked dummy); // Return true if the interval (which is closed) contains the point 'p'. // Skips the normalization of 'p' from -Pi to Pi. bool FastContains(double p) const; Vector2_d bounds_; }; inline S1Interval::S1Interval(double lo, double hi) : bounds_(lo, hi) { if (lo == -M_PI && hi != M_PI) set_lo(M_PI); if (hi == -M_PI && lo != M_PI) set_hi(M_PI); ABSL_DCHECK(is_valid()); } inline S1Interval::S1Interval(double lo, double hi, ArgsChecked dummy) : bounds_(lo, hi) { ABSL_DCHECK(is_valid()); } inline S1Interval::S1Interval() : bounds_(M_PI, -M_PI) { } inline S1Interval S1Interval::Empty() { return S1Interval(); } inline S1Interval S1Interval::Full() { return S1Interval(-M_PI, M_PI, ARGS_CHECKED); } inline bool S1Interval::is_valid() const { return (std::fabs(lo()) <= M_PI && std::fabs(hi()) <= M_PI && !(lo() == -M_PI && hi() != M_PI) && !(hi() == -M_PI && lo() != M_PI)); } inline bool S1Interval::operator==(const S1Interval& y) const { return lo() == y.lo() && hi() == y.hi(); } inline bool S1Interval::operator!=(const S1Interval& y) const { return !operator==(y); } inline void S1Interval::set_lo(double p) { bounds_[0] = p; ABSL_DCHECK(is_valid()); } inline void S1Interval::set_hi(double p) { bounds_[1] = p; ABSL_DCHECK(is_valid()); } inline std::ostream& operator<<(std::ostream& os, const S1Interval& x) { return os << "[" << x.lo() << ", " << x.hi() << "]"; } template H AbslHashValue(H h, const S1Interval& interval) { return H::combine(std::move(h), interval.lo(), interval.hi()); } #endif // S2_S1INTERVAL_H_ src/s2/s1interval_test.cc000066400000000000000000000521071524103652300156350ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s1interval.h" #include #include #include #include #include "absl/hash/hash_testing.h" #include "absl/strings/string_view.h" using absl::string_view; using std::fabs; class S1IntervalTestBase : public testing::Test { public: // Create some standard intervals to use in the tests. These include the // empty and full intervals, intervals containing a single point, and // intervals spanning one or more "quadrants" which are numbered as follows: // quad1 == [0, Pi/2] // quad2 == [Pi/2, Pi] // quad3 == [-Pi, -Pi/2] // quad4 == [-Pi/2, 0] S1IntervalTestBase() : empty(S1Interval::Empty()), full(S1Interval::Full()), // Single-point intervals: zero(0, 0), pi2(M_PI_2, M_PI_2), pi(M_PI, M_PI), mipi(-M_PI, -M_PI), // Same as "pi" after normalization. mipi2(-M_PI_2, -M_PI_2), // Single quadrants: quad1(0, M_PI_2), quad2(M_PI_2, -M_PI), quad3(M_PI, -M_PI_2), quad4(-M_PI_2, 0), // Quadrant pairs: quad12(0, -M_PI), quad23(M_PI_2, -M_PI_2), quad34(-M_PI, 0), quad41(-M_PI_2, M_PI_2), // Quadrant triples: quad123(0, -M_PI_2), quad234(M_PI_2, 0), quad341(M_PI, M_PI_2), quad412(-M_PI_2, -M_PI), // Small intervals around the midpoints between quadrants, such that // the center of each interval is offset slightly CCW from the midpoint. mid12(M_PI_2 - 0.01, M_PI_2 + 0.02), mid23(M_PI - 0.01, -M_PI + 0.02), mid34(-M_PI_2 - 0.01, -M_PI_2 + 0.02), mid41(-0.01, 0.02) { } protected: const S1Interval empty, full; const S1Interval zero, pi2, pi, mipi, mipi2; const S1Interval quad1, quad2, quad3, quad4; const S1Interval quad12, quad23, quad34, quad41; const S1Interval quad123, quad234, quad341, quad412; const S1Interval mid12, mid23, mid34, mid41; }; TEST_F(S1IntervalTestBase, ConstructorsAndAccessors) { // Spot-check the constructors and accessors. EXPECT_EQ(quad12.lo(), 0); EXPECT_EQ(quad12.hi(), M_PI); EXPECT_EQ(quad34[0], M_PI); EXPECT_EQ(quad34[1], 0); EXPECT_EQ(quad34.bounds(), Vector2_d(M_PI, 0)); EXPECT_EQ(pi.lo(), M_PI); EXPECT_EQ(pi.hi(), M_PI); // Check that [-Pi, -Pi] is normalized to [Pi, Pi]. EXPECT_EQ(mipi.lo(), M_PI); EXPECT_EQ(mipi.hi(), M_PI); EXPECT_EQ(quad23.lo(), M_PI_2); EXPECT_EQ(quad23.hi(), -M_PI_2); // Check that the default S1Interval is identical to Empty(). S1Interval default_empty; EXPECT_TRUE(default_empty.is_valid()); EXPECT_TRUE(default_empty.is_empty()); EXPECT_EQ(empty.lo(), default_empty.lo()); EXPECT_EQ(empty.hi(), default_empty.hi()); } TEST_F(S1IntervalTestBase, SimplePredicates) { // is_valid(), is_empty(), is_full(), is_inverted() EXPECT_TRUE(zero.is_valid() && !zero.is_empty() && !zero.is_full()); EXPECT_TRUE(empty.is_valid() && empty.is_empty() && !empty.is_full()); EXPECT_TRUE(empty.is_inverted()); EXPECT_TRUE(full.is_valid() && !full.is_empty() && full.is_full()); EXPECT_TRUE(!quad12.is_empty() && !quad12.is_full() && !quad12.is_inverted()); EXPECT_TRUE(!quad23.is_empty() && !quad23.is_full() && quad23.is_inverted()); EXPECT_TRUE(pi.is_valid() && !pi.is_empty() && !pi.is_inverted()); EXPECT_TRUE(mipi.is_valid() && !mipi.is_empty() && !mipi.is_inverted()); } TEST(S1IntervalTest, IsValidPoint) { // Valid angles: endpoints of the allowed range and interior values. EXPECT_TRUE(S1Interval::IsValidPoint(0)); EXPECT_TRUE(S1Interval::IsValidPoint(M_PI)); EXPECT_TRUE(S1Interval::IsValidPoint(-M_PI)); // Invalid: strictly outside [-Pi, Pi]. EXPECT_FALSE(S1Interval::IsValidPoint(M_PI + 1e-15)); EXPECT_FALSE(S1Interval::IsValidPoint(-M_PI - 1e-15)); EXPECT_FALSE(S1Interval::IsValidPoint(4.0)); EXPECT_FALSE(S1Interval::IsValidPoint(-4.0)); } TEST_F(S1IntervalTestBase, AlmostEmptyOrFull) { // Test that rounding errors don't cause intervals that are almost empty or // full to be considered empty or full. The following value is the greatest // representable value less than Pi. const double kAlmostPi = M_PI - 2 * DBL_EPSILON; EXPECT_FALSE(S1Interval(-kAlmostPi, M_PI).is_full()); EXPECT_FALSE(S1Interval(-M_PI, kAlmostPi).is_full()); EXPECT_FALSE(S1Interval(M_PI, -kAlmostPi).is_empty()); EXPECT_FALSE(S1Interval(kAlmostPi, -M_PI).is_empty()); } TEST_F(S1IntervalTestBase, GetCenter) { EXPECT_EQ(quad12.GetCenter(), M_PI_2); EXPECT_DOUBLE_EQ(S1Interval(3.1, 2.9).GetCenter(), 3.0 - M_PI); EXPECT_DOUBLE_EQ(S1Interval(-2.9, -3.1).GetCenter(), M_PI - 3.0); EXPECT_DOUBLE_EQ(S1Interval(2.1, -2.1).GetCenter(), M_PI); EXPECT_EQ(pi.GetCenter(), M_PI); EXPECT_EQ(mipi.GetCenter(), M_PI); EXPECT_EQ(fabs(quad23.GetCenter()), M_PI); EXPECT_DOUBLE_EQ(quad123.GetCenter(), 0.75 * M_PI); } TEST_F(S1IntervalTestBase, GetLength) { EXPECT_EQ(quad12.GetLength(), M_PI); EXPECT_EQ(pi.GetLength(), 0); EXPECT_EQ(mipi.GetLength(), 0); EXPECT_DOUBLE_EQ(quad123.GetLength(), 1.5 * M_PI); EXPECT_EQ(fabs(quad23.GetLength()), M_PI); EXPECT_EQ(full.GetLength(), 2 * M_PI); EXPECT_LT(empty.GetLength(), 0); } TEST_F(S1IntervalTestBase, Complement) { EXPECT_TRUE(empty.Complement().is_full()); EXPECT_TRUE(full.Complement().is_empty()); EXPECT_TRUE(pi.Complement().is_full()); EXPECT_TRUE(mipi.Complement().is_full()); EXPECT_TRUE(zero.Complement().is_full()); EXPECT_TRUE(quad12.Complement().ApproxEquals(quad34)); EXPECT_TRUE(quad34.Complement().ApproxEquals(quad12)); EXPECT_TRUE(quad123.Complement().ApproxEquals(quad4)); } TEST_F(S1IntervalTestBase, Contains) { // Contains(double), InteriorContains(double) EXPECT_TRUE(!empty.Contains(0) && !empty.Contains(M_PI) && !empty.Contains(-M_PI)); EXPECT_TRUE(!empty.InteriorContains(M_PI) && !empty.InteriorContains(-M_PI)); EXPECT_TRUE(full.Contains(0) && full.Contains(M_PI) && full.Contains(-M_PI)); EXPECT_TRUE(full.InteriorContains(M_PI) && full.InteriorContains(-M_PI)); EXPECT_TRUE(quad12.Contains(0) && quad12.Contains(M_PI) && quad12.Contains(-M_PI)); EXPECT_TRUE(quad12.InteriorContains(M_PI_2) && !quad12.InteriorContains(0)); EXPECT_TRUE(!quad12.InteriorContains(M_PI) && !quad12.InteriorContains(-M_PI)); EXPECT_TRUE(quad23.Contains(M_PI_2) && quad23.Contains(-M_PI_2)); EXPECT_TRUE(quad23.Contains(M_PI) && quad23.Contains(-M_PI)); EXPECT_TRUE(!quad23.Contains(0)); EXPECT_TRUE(!quad23.InteriorContains(M_PI_2) && !quad23.InteriorContains(-M_PI_2)); EXPECT_TRUE(quad23.InteriorContains(M_PI) && quad23.InteriorContains(-M_PI)); EXPECT_TRUE(!quad23.InteriorContains(0)); EXPECT_TRUE(pi.Contains(M_PI) && pi.Contains(-M_PI) && !pi.Contains(0)); EXPECT_TRUE(!pi.InteriorContains(M_PI) && !pi.InteriorContains(-M_PI)); EXPECT_TRUE(mipi.Contains(M_PI) && mipi.Contains(-M_PI) && !mipi.Contains(0)); EXPECT_TRUE(!mipi.InteriorContains(M_PI) && !mipi.InteriorContains(-M_PI)); EXPECT_TRUE(zero.Contains(0) && !zero.InteriorContains(0)); } static void TestIntervalOps(const S1Interval& x, const S1Interval& y, string_view expected_relation, const S1Interval& expected_union, const S1Interval& expected_intersection) { // Test all of the interval operations on the given pair of intervals. // "expected_relation" is a sequence of "T" and "F" characters corresponding // to the expected results of Contains(), InteriorContains(), Intersects(), // and InteriorIntersects() respectively. EXPECT_EQ(x.Contains(y), expected_relation[0] == 'T'); EXPECT_EQ(x.InteriorContains(y), expected_relation[1] == 'T'); EXPECT_EQ(x.Intersects(y), expected_relation[2] == 'T'); EXPECT_EQ(x.InteriorIntersects(y), expected_relation[3] == 'T'); // bounds() returns a const reference to a member variable, so we need to // make a copy when invoking it on a temporary object. EXPECT_EQ(Vector2_d(x.Union(y).bounds()), expected_union.bounds()); EXPECT_EQ(Vector2_d(x.Intersection(y).bounds()), expected_intersection.bounds()); EXPECT_EQ(x.Contains(y), x.Union(y) == x); EXPECT_EQ(x.Intersects(y), !x.Intersection(y).is_empty()); if (y.lo() == y.hi()) { S1Interval r = x; r.AddPoint(y.lo()); EXPECT_EQ(r.bounds(), expected_union.bounds()); } } TEST_F(S1IntervalTestBase, IntervalOps) { // Contains(S1Interval), InteriorContains(S1Interval), // Intersects(), InteriorIntersects(), Union(), Intersection() TestIntervalOps(empty, empty, "TTFF", empty, empty); TestIntervalOps(empty, full, "FFFF", full, empty); TestIntervalOps(empty, zero, "FFFF", zero, empty); TestIntervalOps(empty, pi, "FFFF", pi, empty); TestIntervalOps(empty, mipi, "FFFF", mipi, empty); TestIntervalOps(full, empty, "TTFF", full, empty); TestIntervalOps(full, full, "TTTT", full, full); TestIntervalOps(full, zero, "TTTT", full, zero); TestIntervalOps(full, pi, "TTTT", full, pi); TestIntervalOps(full, mipi, "TTTT", full, mipi); TestIntervalOps(full, quad12, "TTTT", full, quad12); TestIntervalOps(full, quad23, "TTTT", full, quad23); TestIntervalOps(zero, empty, "TTFF", zero, empty); TestIntervalOps(zero, full, "FFTF", full, zero); TestIntervalOps(zero, zero, "TFTF", zero, zero); TestIntervalOps(zero, pi, "FFFF", S1Interval(0, M_PI), empty); TestIntervalOps(zero, pi2, "FFFF", quad1, empty); TestIntervalOps(zero, mipi, "FFFF", quad12, empty); TestIntervalOps(zero, mipi2, "FFFF", quad4, empty); TestIntervalOps(zero, quad12, "FFTF", quad12, zero); TestIntervalOps(zero, quad23, "FFFF", quad123, empty); TestIntervalOps(pi2, empty, "TTFF", pi2, empty); TestIntervalOps(pi2, full, "FFTF", full, pi2); TestIntervalOps(pi2, zero, "FFFF", quad1, empty); TestIntervalOps(pi2, pi, "FFFF", S1Interval(M_PI_2, M_PI), empty); TestIntervalOps(pi2, pi2, "TFTF", pi2, pi2); TestIntervalOps(pi2, mipi, "FFFF", quad2, empty); TestIntervalOps(pi2, mipi2, "FFFF", quad23, empty); TestIntervalOps(pi2, quad12, "FFTF", quad12, pi2); TestIntervalOps(pi2, quad23, "FFTF", quad23, pi2); TestIntervalOps(pi, empty, "TTFF", pi, empty); TestIntervalOps(pi, full, "FFTF", full, pi); TestIntervalOps(pi, zero, "FFFF", S1Interval(M_PI, 0), empty); TestIntervalOps(pi, pi, "TFTF", pi, pi); TestIntervalOps(pi, pi2, "FFFF", S1Interval(M_PI_2, M_PI), empty); TestIntervalOps(pi, mipi, "TFTF", pi, pi); TestIntervalOps(pi, mipi2, "FFFF", quad3, empty); TestIntervalOps(pi, quad12, "FFTF", S1Interval(0, M_PI), pi); TestIntervalOps(pi, quad23, "FFTF", quad23, pi); TestIntervalOps(mipi, empty, "TTFF", mipi, empty); TestIntervalOps(mipi, full, "FFTF", full, mipi); TestIntervalOps(mipi, zero, "FFFF", quad34, empty); TestIntervalOps(mipi, pi, "TFTF", mipi, mipi); TestIntervalOps(mipi, pi2, "FFFF", quad2, empty); TestIntervalOps(mipi, mipi, "TFTF", mipi, mipi); TestIntervalOps(mipi, mipi2, "FFFF", S1Interval(-M_PI, -M_PI_2), empty); TestIntervalOps(mipi, quad12, "FFTF", quad12, mipi); TestIntervalOps(mipi, quad23, "FFTF", quad23, mipi); TestIntervalOps(quad12, empty, "TTFF", quad12, empty); TestIntervalOps(quad12, full, "FFTT", full, quad12); TestIntervalOps(quad12, zero, "TFTF", quad12, zero); TestIntervalOps(quad12, pi, "TFTF", quad12, pi); TestIntervalOps(quad12, mipi, "TFTF", quad12, mipi); TestIntervalOps(quad12, quad12, "TFTT", quad12, quad12); TestIntervalOps(quad12, quad23, "FFTT", quad123, quad2); TestIntervalOps(quad12, quad34, "FFTF", full, quad12); TestIntervalOps(quad23, empty, "TTFF", quad23, empty); TestIntervalOps(quad23, full, "FFTT", full, quad23); TestIntervalOps(quad23, zero, "FFFF", quad234, empty); TestIntervalOps(quad23, pi, "TTTT", quad23, pi); TestIntervalOps(quad23, mipi, "TTTT", quad23, mipi); TestIntervalOps(quad23, quad12, "FFTT", quad123, quad2); TestIntervalOps(quad23, quad23, "TFTT", quad23, quad23); TestIntervalOps(quad23, quad34, "FFTT", quad234, S1Interval(-M_PI, -M_PI_2)); TestIntervalOps(quad1, quad23, "FFTF", quad123, S1Interval(M_PI_2, M_PI_2)); TestIntervalOps(quad2, quad3, "FFTF", quad23, mipi); TestIntervalOps(quad3, quad2, "FFTF", quad23, pi); TestIntervalOps(quad2, pi, "TFTF", quad2, pi); TestIntervalOps(quad2, mipi, "TFTF", quad2, mipi); TestIntervalOps(quad3, pi, "TFTF", quad3, pi); TestIntervalOps(quad3, mipi, "TFTF", quad3, mipi); TestIntervalOps(quad12, mid12, "TTTT", quad12, mid12); TestIntervalOps(mid12, quad12, "FFTT", quad12, mid12); S1Interval quad12eps(quad12.lo(), mid23.hi()); S1Interval quad2hi(mid23.lo(), quad12.hi()); TestIntervalOps(quad12, mid23, "FFTT", quad12eps, quad2hi); TestIntervalOps(mid23, quad12, "FFTT", quad12eps, quad2hi); // This test checks that the union of two disjoint intervals is the smallest // interval that contains both of them. Note that the center of "mid34" is // slightly CCW of -Pi/2 so that there is no ambiguity about the result. S1Interval quad412eps(mid34.lo(), quad12.hi()); TestIntervalOps(quad12, mid34, "FFFF", quad412eps, empty); TestIntervalOps(mid34, quad12, "FFFF", quad412eps, empty); S1Interval quadeps12(mid41.lo(), quad12.hi()); S1Interval quad1lo(quad12.lo(), mid41.hi()); TestIntervalOps(quad12, mid41, "FFTT", quadeps12, quad1lo); TestIntervalOps(mid41, quad12, "FFTT", quadeps12, quad1lo); S1Interval quad2lo(quad23.lo(), mid12.hi()); S1Interval quad3hi(mid34.lo(), quad23.hi()); S1Interval quadeps23(mid12.lo(), quad23.hi()); S1Interval quad23eps(quad23.lo(), mid34.hi()); S1Interval quadeps123(mid41.lo(), quad23.hi()); TestIntervalOps(quad23, mid12, "FFTT", quadeps23, quad2lo); TestIntervalOps(mid12, quad23, "FFTT", quadeps23, quad2lo); TestIntervalOps(quad23, mid23, "TTTT", quad23, mid23); TestIntervalOps(mid23, quad23, "FFTT", quad23, mid23); TestIntervalOps(quad23, mid34, "FFTT", quad23eps, quad3hi); TestIntervalOps(mid34, quad23, "FFTT", quad23eps, quad3hi); TestIntervalOps(quad23, mid41, "FFFF", quadeps123, empty); TestIntervalOps(mid41, quad23, "FFFF", quadeps123, empty); } TEST_F(S1IntervalTestBase, AddPoint) { S1Interval r = empty; r.AddPoint(0); EXPECT_EQ(r, zero); r = empty; r.AddPoint(M_PI); EXPECT_EQ(r, pi); r = empty; r.AddPoint(-M_PI); EXPECT_EQ(r, mipi); r = empty; r.AddPoint(M_PI); r.AddPoint(-M_PI); EXPECT_EQ(r, pi); r = empty; r.AddPoint(-M_PI); r.AddPoint(M_PI); EXPECT_EQ(r, mipi); r = empty; r.AddPoint(mid12.lo()); r.AddPoint(mid12.hi()); EXPECT_EQ(r, mid12); r = empty; r.AddPoint(mid23.lo()); r.AddPoint(mid23.hi()); EXPECT_EQ(r, mid23); r = quad1; r.AddPoint(-0.9*M_PI); r.AddPoint(-M_PI_2); EXPECT_EQ(r, quad123); r = full; r.AddPoint(0); EXPECT_TRUE(r.is_full()); r = full; r.AddPoint(M_PI); EXPECT_TRUE(r.is_full()); r = full; r.AddPoint(-M_PI); EXPECT_TRUE(r.is_full()); } TEST_F(S1IntervalTestBase, Project) { S1Interval r(-M_PI, -M_PI); EXPECT_EQ(M_PI, r.Project(-M_PI)); EXPECT_EQ(M_PI, r.Project(0)); r = S1Interval(0, M_PI); EXPECT_EQ(0.1, r.Project(0.1)); EXPECT_EQ(0, r.Project(-M_PI_2 + 1e-15)); EXPECT_EQ(M_PI, r.Project(-M_PI_2 - 1e-15)); r = S1Interval(M_PI - 0.1, -M_PI + 0.1); EXPECT_EQ(M_PI, r.Project(M_PI)); EXPECT_EQ(M_PI - 0.1, r.Project(1e-15)); EXPECT_EQ(-M_PI + 0.1, r.Project(-1e-15)); EXPECT_EQ(0, S1Interval::Full().Project(0)); EXPECT_EQ(M_PI, S1Interval::Full().Project(M_PI)); EXPECT_EQ(M_PI, S1Interval::Full().Project(-M_PI)); } TEST_F(S1IntervalTestBase, FromPointPair) { EXPECT_EQ(S1Interval::FromPointPair(-M_PI, M_PI), pi); EXPECT_EQ(S1Interval::FromPointPair(M_PI, -M_PI), pi); EXPECT_EQ(S1Interval::FromPointPair(mid34.hi(), mid34.lo()), mid34); EXPECT_EQ(S1Interval::FromPointPair(mid23.lo(), mid23.hi()), mid23); } TEST_F(S1IntervalTestBase, Expanded) { EXPECT_EQ(empty.Expanded(1), empty); EXPECT_EQ(full.Expanded(1), full); EXPECT_EQ(zero.Expanded(1), S1Interval(-1, 1)); EXPECT_EQ(mipi.Expanded(0.01), S1Interval(M_PI - 0.01, -M_PI + 0.01)); EXPECT_EQ(pi.Expanded(27), full); EXPECT_EQ(pi.Expanded(M_PI_2), quad23); EXPECT_EQ(pi2.Expanded(M_PI_2), quad12); EXPECT_EQ(mipi2.Expanded(M_PI_2), quad34); EXPECT_EQ(empty.Expanded(-1), empty); EXPECT_EQ(full.Expanded(-1), full); EXPECT_EQ(quad123.Expanded(-27), empty); EXPECT_EQ(quad234.Expanded(-27), empty); EXPECT_EQ(quad123.Expanded(-M_PI_2), quad2); EXPECT_EQ(quad341.Expanded(-M_PI_2), quad4); EXPECT_EQ(quad412.Expanded(-M_PI_2), quad1); } TEST_F(S1IntervalTestBase, ApproxEquals) { // Choose two values kLo and kHi such that it's okay to shift an endpoint by // kLo (i.e., the resulting interval is equivalent) but not by kHi. static const double kLo = 4 * DBL_EPSILON; // < max_error default static const double kHi = 6 * DBL_EPSILON; // > max_error default // Empty intervals. EXPECT_TRUE(empty.ApproxEquals(empty)); EXPECT_TRUE(zero.ApproxEquals(empty) && empty.ApproxEquals(zero)); EXPECT_TRUE(pi.ApproxEquals(empty) && empty.ApproxEquals(pi)); EXPECT_TRUE(mipi.ApproxEquals(empty) && empty.ApproxEquals(mipi)); EXPECT_FALSE(empty.ApproxEquals(full)); EXPECT_TRUE(empty.ApproxEquals(S1Interval(1, 1 + 2*kLo))); EXPECT_FALSE(empty.ApproxEquals(S1Interval(1, 1 + 2*kHi))); EXPECT_TRUE(S1Interval(M_PI - kLo, -M_PI + kLo).ApproxEquals(empty)); // Full intervals. EXPECT_TRUE(full.ApproxEquals(full)); EXPECT_FALSE(full.ApproxEquals(empty)); EXPECT_FALSE(full.ApproxEquals(zero)); EXPECT_FALSE(full.ApproxEquals(pi)); EXPECT_TRUE(full.ApproxEquals(S1Interval(kLo, -kLo))); EXPECT_FALSE(full.ApproxEquals(S1Interval(2*kHi, 0))); EXPECT_TRUE(S1Interval(-M_PI + kLo, M_PI - kLo).ApproxEquals(full)); EXPECT_FALSE(S1Interval(-M_PI, M_PI - 2*kHi).ApproxEquals(full)); // Singleton intervals. EXPECT_TRUE(pi.ApproxEquals(pi) && mipi.ApproxEquals(pi)); EXPECT_TRUE(pi.ApproxEquals(S1Interval(M_PI - kLo, M_PI - kLo))); EXPECT_FALSE(pi.ApproxEquals(S1Interval(M_PI - kHi, M_PI - kHi))); EXPECT_TRUE(pi.ApproxEquals(S1Interval(M_PI - kLo, -M_PI + kLo))); EXPECT_FALSE(pi.ApproxEquals(S1Interval(M_PI - kHi, -M_PI))); EXPECT_FALSE(zero.ApproxEquals(pi)); EXPECT_TRUE(pi.Union(mid12).Union(zero).ApproxEquals(quad12)); EXPECT_TRUE(quad2.Intersection(quad3).ApproxEquals(pi)); EXPECT_TRUE(quad3.Intersection(quad2).ApproxEquals(pi)); // Intervals whose corresponding endpoints are nearly the same but where the // endpoints are in opposite order (i.e., inverted intervals). EXPECT_FALSE(S1Interval(0, kLo).ApproxEquals(S1Interval(kLo, 0))); EXPECT_FALSE(S1Interval(M_PI - 0.5 * kLo, -M_PI + 0.5 * kLo). ApproxEquals(S1Interval(-M_PI + 0.5 * kLo, M_PI - 0.5 * kLo))); // Other intervals. EXPECT_TRUE(S1Interval(1 - kLo, 2 + kLo).ApproxEquals(S1Interval(1, 2))); EXPECT_TRUE(S1Interval(1 + kLo, 2 - kLo).ApproxEquals(S1Interval(1, 2))); EXPECT_TRUE(S1Interval(2 - kLo, 1 + kLo).ApproxEquals(S1Interval(2, 1))); EXPECT_TRUE(S1Interval(2 + kLo, 1 - kLo).ApproxEquals(S1Interval(2, 1))); EXPECT_FALSE(S1Interval(1 - kHi, 2 + kLo).ApproxEquals(S1Interval(1, 2))); EXPECT_FALSE(S1Interval(1 + kHi, 2 - kLo).ApproxEquals(S1Interval(1, 2))); EXPECT_FALSE(S1Interval(2 - kHi, 1 + kLo).ApproxEquals(S1Interval(2, 1))); EXPECT_FALSE(S1Interval(2 + kHi, 1 - kLo).ApproxEquals(S1Interval(2, 1))); EXPECT_FALSE(S1Interval(1 - kLo, 2 + kHi).ApproxEquals(S1Interval(1, 2))); EXPECT_FALSE(S1Interval(1 + kLo, 2 - kHi).ApproxEquals(S1Interval(1, 2))); EXPECT_FALSE(S1Interval(2 - kLo, 1 + kHi).ApproxEquals(S1Interval(2, 1))); EXPECT_FALSE(S1Interval(2 + kLo, 1 - kHi).ApproxEquals(S1Interval(2, 1))); } TEST_F(S1IntervalTestBase, OperatorEquals) { EXPECT_EQ(empty, empty); EXPECT_EQ(full, full); EXPECT_NE(full, empty); } TEST_F(S1IntervalTestBase, GetDirectedHausdorffDistance) { EXPECT_FLOAT_EQ(0.0, empty.GetDirectedHausdorffDistance(empty)); EXPECT_FLOAT_EQ(0.0, empty.GetDirectedHausdorffDistance(mid12)); EXPECT_FLOAT_EQ(M_PI, mid12.GetDirectedHausdorffDistance(empty)); EXPECT_EQ(0.0, quad12.GetDirectedHausdorffDistance(quad123)); S1Interval in(3.0, -3.0); // an interval whose complement center is 0. EXPECT_FLOAT_EQ(3.0, S1Interval(-0.1, 0.2).GetDirectedHausdorffDistance(in)); EXPECT_FLOAT_EQ(3.0 - 0.1, S1Interval(0.1, 0.2).GetDirectedHausdorffDistance(in)); EXPECT_FLOAT_EQ(3.0 - 0.1, S1Interval(-0.2, -0.1).GetDirectedHausdorffDistance(in)); } TEST(S1Interval, SupportsAbslHash) { EXPECT_TRUE(absl::VerifyTypeImplementsAbslHashCorrectly({ S1Interval::Empty(), S1Interval::Full(), S1Interval(0, 1), S1Interval(-1, 1), S1Interval(M_PI / 2, M_PI), S1Interval(-M_PI, -M_PI / 2), S1Interval(M_PI - 0.1, -M_PI + 0.1), // inverted (wraps around) })); } src/s2/s2boolean_operation.cc000066400000000000000000003574431524103652300164650ustar00rootroot00000000000000// Copyright 2017 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) // // Boolean operations are implemented by constructing the boundary of the // result and then using S2Builder to assemble the edges. The boundary is // obtained by clipping each of the two input regions to the interior or // exterior of the other region. For example, to compute the union of A and // B, we clip the boundary of A to the exterior of B and the boundary of B to // the exterior of A; the resulting set of edges defines the union of the two // regions. // // We use exact predicates, but inexact constructions (e.g. computing the // intersection point of two edges). Nevertheless, the following algorithm is // guaranteed to be 100% robust, in that the computed boundary stays within a // small tolerance (snap_radius + S2::kIntersectionError) of the exact // result, and also preserves the correct topology (i.e., no crossing edges). // // Unfortunately this robustness cannot quite be achieved using the strategy // outlined above (clipping the two input regions and assembling the // resulting edges). Since computed intersection points are not exact, the // input geometry passed to S2Builder might contain self-intersections, and // these self-intersections cannot be eliminated reliably by snap rounding. // // So instead, we pass S2Builder the entire set of input edges where at least // some portion of each edge belongs to the output boundary. We allow // S2Builder to compute the intersection points and snap round the edges // (which it does in a way that is guaranteed to preserve the input topology). // Then once this is finished, we remove the portions of each edge that would // have been clipped if we had done the clipping first. This step only // involves deciding whether to keep or discard each edge in the output, since // all intersection points have already been resolved, and therefore there is // no risk of creating new self-intersections. // // This is implemented using the following classes: // // - S2BooleanOperation::Impl: the top-level class that clips each of // the two regions to the other region. // // - CrossingProcessor: a class that processes edge crossings and maintains // the necessary state in order to clip the boundary // of one region to the interior or exterior of the // other region. // // - EdgeClippingLayer: an S2Builder::Layer that removes graph edges that // correspond to clipped portions of input edges, and // passes the result to another layer for assembly. // // - GraphEdgeClipper: a helper class that does the actual work of the // EdgeClippingLayer. #include "s2/s2boolean_operation.h" #include #include #include #include #include #include #include #include #include #include #include "absl/base/nullability.h" #include "absl/cleanup/cleanup.h" #include "absl/container/btree_map.h" #include "absl/container/flat_hash_map.h" #include "absl/container/inlined_vector.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/strings/string_view.h" #include "absl/types/span.h" #include "s2/id_set_lexicon.h" #include "s2/s1angle.h" #include "s2/s2builder.h" #include "s2/s2builder_graph.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_snap_functions.h" #include "s2/s2cell_id.h" #include "s2/s2contains_point_query.h" #include "s2/s2crossing_edge_query.h" #include "s2/s2edge_crossings.h" #include "s2/s2error.h" #include "s2/s2measures.h" #include "s2/s2memory_tracker.h" #include "s2/s2point.h" #include "s2/s2predicates.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2shape_index_measures.h" #include "s2/s2shapeutil_shape_edge.h" #include "s2/s2shapeutil_shape_edge_id.h" #include "s2/s2shapeutil_visit_crossing_edge_pairs.h" #include "s2/value_lexicon.h" namespace { // Anonymous namespace for helper classes. using absl::flat_hash_map; using absl::string_view; using std::lower_bound; using std::make_pair; using std::make_unique; using std::max; using std::min; using std::pair; using std::swap; using std::unique_ptr; using std::vector; using EdgeType = S2Builder::EdgeType; using SnapFunction = S2Builder::SnapFunction; using GraphOptions = S2Builder::GraphOptions; using DegenerateEdges = GraphOptions::DegenerateEdges; using DuplicateEdges = GraphOptions::DuplicateEdges; using SiblingPairs = GraphOptions::SiblingPairs; using Graph = S2Builder::Graph; using EdgeId = Graph::EdgeId; using VertexId = Graph::VertexId; using InputEdgeId = Graph::InputEdgeId; using InputEdgeIdSetId = Graph::InputEdgeIdSetId; using PolygonModel = S2BooleanOperation::PolygonModel; using PolylineModel = S2BooleanOperation::PolylineModel; using Precision = S2BooleanOperation::Precision; // A collection of special InputEdgeIds that allow the GraphEdgeClipper state // modifications to be inserted into the list of edge crossings. static const InputEdgeId kSetInside = -1; static const InputEdgeId kSetInvertB = -2; static const InputEdgeId kSetReverseA = -3; // CrossingInputEdge represents an input edge B that crosses some other input // edge A. It stores the input edge id of edge B and also whether it crosses // edge A from left to right (or vice versa). class CrossingInputEdge { public: // Indicates that input edge "input_id" crosses another edge (from left to // right if "left_to_right" is true). CrossingInputEdge(InputEdgeId input_id, bool left_to_right) : left_to_right_(left_to_right), input_id_(input_id) { } InputEdgeId input_id() const { return input_id_; } bool left_to_right() const { return left_to_right_; } bool operator<(const CrossingInputEdge& other) const { return input_id_ < other.input_id_; } bool operator<(const InputEdgeId& other) const { return input_id_ < other; } private: bool left_to_right_ : 1; InputEdgeId input_id_ : 31; }; // InputEdgeCrossings represents all pairs of intersecting input edges and // also certain GraphEdgeClipper state modifications (kSetInside, etc). // It is sorted lexicographically except for entries representing state // modifications, which are sorted by the first InputEdgeId only. using InputEdgeCrossings = vector>; // Given two input edges A and B that intersect, suppose that A maps to a // chain of snapped edges A_0, A_1, ..., A_m and B maps to a chain of snapped // edges B_0, B_1, ..., B_n. CrossingGraphEdge represents an edge from chain // B that shares a vertex with chain A. It is used as a temporary data // representation while processing chain A. The arguments are: // // "id" - the Graph::EdgeId of an edge from chain B. // "a_index" - the index of the vertex (A_i) that is shared with chain A. // "outgoing" - true if the shared vertex is the first vertex of the B edge. // "dst" - the Graph::VertexId of the vertex that is not shared with chain A. // // Note that if an edge from the B chain shares both vertices with the A // chain, there will be two entries: an outgoing edge that treats its first // vertex as being shared, and an incoming edge that treats its second vertex // as being shared. struct CrossingGraphEdge { CrossingGraphEdge(EdgeId _id, int _a_index, bool _outgoing, VertexId _dst) : id(_id), a_index(_a_index), outgoing(_outgoing), dst(_dst) { } EdgeId id; int a_index; bool outgoing; VertexId dst; }; using CrossingGraphEdgeVector = absl::InlinedVector; // Returns a vector of EdgeIds sorted by input edge id. When more than one // output edge has the same input edge id (i.e., the input edge snapped to a // chain of edges), the edges are sorted so that they form a directed edge // chain. // // This function could possibly be moved to S2Builder::Graph, but note that // it has special requirements. Namely, duplicate edges and sibling pairs // must be kept in order to ensure that every output edge corresponds to // exactly one input edge. (See also S2Builder::Graph::GetInputEdgeOrder.) static vector GetInputEdgeChainOrder( const Graph& g, absl::Span input_ids) { ABSL_DCHECK(g.options().edge_type() == EdgeType::DIRECTED); ABSL_DCHECK(g.options().duplicate_edges() == DuplicateEdges::KEEP); ABSL_DCHECK(g.options().sibling_pairs() == SiblingPairs::KEEP); // First, sort the edges so that the edges corresponding to each input edge // are consecutive. (Each input edge was snapped to a chain of output // edges, or two chains in the case of undirected input edges.) vector order = g.GetInputEdgeOrder(input_ids); // Now sort the group of edges corresponding to each input edge in edge // chain order (e.g. AB, BC, CD). vector> vmap; // Map from source vertex to edge id. vector indegree(g.num_vertices()); // Restricted to current input edge. for (size_t end, begin = 0; begin < order.size(); begin = end) { // Gather the edges that came from a single input edge. InputEdgeId input_id = input_ids[order[begin]]; for (end = begin; end < order.size(); ++end) { if (input_ids[order[end]] != input_id) break; } if (end - begin == 1) continue; // Build a map from the source vertex of each edge to its edge id, // and also compute the indegree at each vertex considering only the edges // that came from the current input edge. for (size_t i = begin; i < end; ++i) { EdgeId e = order[i]; vmap.push_back(make_pair(g.edge(e).first, e)); indegree[g.edge(e).second] += 1; } std::sort(vmap.begin(), vmap.end()); // Find the starting edge for building the edge chain. EdgeId next = g.num_edges(); for (size_t i = begin; i < end; ++i) { EdgeId e = order[i]; if (indegree[g.edge(e).first] == 0) next = e; } // Build the edge chain. for (size_t i = begin;;) { order[i] = next; VertexId v = g.edge(next).second; indegree[v] = 0; // Clear as we go along. if (++i == end) break; auto out = lower_bound(vmap.begin(), vmap.end(), make_pair(v, 0)); ABSL_DCHECK_EQ(v, out->first); next = out->second; } vmap.clear(); } return order; } // Given a set of clipping instructions encoded as an InputEdgeCrossings, // GraphEdgeClipper determines which graph edges correspond to clipped // portions of input edges and removes them. // // The clipping model is as follows. The input consists of edge chains. The // clipper maintains an "inside" boolean state as it clips each chain, and // toggles this state whenever an input edge is crossed. Any edges that are // deemed to be "outside" after clipping are removed. // // The "inside" state can be reset when necessary (e.g., when jumping to the // start of a new chain) by adding a special crossing marked kSetInside. // There are also two other special "crossings" that modify the clipping // parameters: kSetInvertB specifies that edges should be clipped to the // exterior of the other region, and kSetReverseA specifies that edges should // be reversed before emitting them (which is needed to implement difference // operations). class GraphEdgeClipper { public: // "input_dimensions" is a vector specifying the dimension of each input // edge (0, 1, or 2). "input_crossings" is the set of all crossings to be // used when clipping the edges of "g", sorted in lexicographic order. // // The clipped set of edges and their corresponding set of input edge ids // are returned in "new_edges" and "new_input_edge_ids". (These can be used // to construct a new S2Builder::Graph.) GraphEdgeClipper(const Graph& g, const vector& input_dimensions, const InputEdgeCrossings& input_crossings, vector* new_edges, vector* new_input_edge_ids); void Run(); private: void AddEdge(Graph::Edge edge, InputEdgeId input_edge_id); void GatherIncidentEdges(absl::Span a, int ai, absl::Span b_input_edges, vector* b_edges) const; int GetCrossedVertexIndex(absl::Span a, const CrossingGraphEdgeVector& b, bool left_to_right) const; int GetVertexRank(const CrossingGraphEdge& e) const; bool EdgeChainOnLeft(absl::Span a, EdgeId b_first, EdgeId b_last) const; const Graph& g_; Graph::VertexInMap in_; Graph::VertexOutMap out_; const vector& input_dimensions_; const InputEdgeCrossings& input_crossings_; vector* new_edges_; vector* new_input_edge_ids_; // Every graph edge is associated with exactly one input edge in our case, // which means that we can declare g_.input_edge_id_set_ids() as a vector of // InputEdgeIds rather than a vector of InputEdgeIdSetIds. (This also takes // advantage of the fact that IdSetLexicon represents a singleton set as the // value of its single element.) const vector& input_ids_; vector order_; // Graph edges sorted in input edge id order. vector rank_; // The rank of each graph edge within order_. }; GraphEdgeClipper::GraphEdgeClipper(const Graph& g, const vector& input_dimensions, const InputEdgeCrossings& input_crossings, vector* new_edges, vector* new_input_edge_ids) : g_(g), in_(g), out_(g), input_dimensions_(input_dimensions), input_crossings_(input_crossings), new_edges_(new_edges), new_input_edge_ids_(new_input_edge_ids), input_ids_(g.input_edge_id_set_ids()), order_(GetInputEdgeChainOrder(g_, input_ids_)), rank_(order_.size()) { for (size_t i = 0; i < order_.size(); ++i) { rank_[order_[i]] = i; } // new_edges_ is obtained by filtering the graph edges and therefore the // number of graph edges is an upper bound on its size. new_edges_->reserve(g_.num_edges()); new_input_edge_ids_->reserve(g_.num_edges()); } inline void GraphEdgeClipper::AddEdge(Graph::Edge edge, InputEdgeId input_edge_id) { new_edges_->push_back(edge); new_input_edge_ids_->push_back(input_edge_id); } void GraphEdgeClipper::Run() { // Declare vectors here and reuse them to avoid reallocation. vector a_vertices; vector a_num_crossings; vector a_isolated; vector b_input_edges; vector b_edges; bool inside = false; bool invert_b = false; bool reverse_a = false; auto next = input_crossings_.begin(); for (size_t i = 0; i < order_.size(); ++i) { // For the current input edge (the "A" input edge), gather all the input // edges that cross it (the "B" input edges). InputEdgeId a_input_id = input_ids_[order_[i]]; const Graph::Edge& edge0 = g_.edge(order_[i]); b_input_edges.clear(); for (; next != input_crossings_.end(); ++next) { if (next->first != a_input_id) break; if (next->second.input_id() >= 0) { b_input_edges.push_back(next->second); } else if (next->second.input_id() == kSetInside) { inside = next->second.left_to_right(); } else if (next->second.input_id() == kSetInvertB) { invert_b = next->second.left_to_right(); } else { ABSL_DCHECK_EQ(next->second.input_id(), kSetReverseA); reverse_a = next->second.left_to_right(); } } // Optimization for degenerate edges. // TODO(ericv): If the output layer for this edge dimension specifies // DegenerateEdges::DISCARD, then remove the edge here. if (edge0.first == edge0.second) { inside ^= (b_input_edges.size() & 1); AddEdge(edge0, a_input_id); continue; } // Optimization for the case where there are no crossings. if (b_input_edges.empty()) { // In general the caller only passes edges that are part of the output // (i.e., we could ABSL_DCHECK(inside) here). The one exception is for // polyline/polygon operations, where the polygon edges are needed to // compute the polyline output but are not emitted themselves. if (inside) { AddEdge(reverse_a ? Graph::reverse(edge0) : edge0, a_input_id); } continue; } // Walk along the chain of snapped edges for input edge A, and at each // vertex collect all the incident edges that belong to one of the // crossing edge chains (the "B" input edges). a_vertices.clear(); a_vertices.push_back(edge0.first); b_edges.clear(); b_edges.resize(b_input_edges.size()); GatherIncidentEdges(a_vertices, 0, b_input_edges, &b_edges); for (; i < order_.size() && input_ids_[order_[i]] == a_input_id; ++i) { a_vertices.push_back(g_.edge(order_[i]).second); GatherIncidentEdges(a_vertices, a_vertices.size() - 1, b_input_edges, &b_edges); } --i; // Now for each B edge chain, decide which vertex of the A chain it // crosses, and keep track of the sum of signed crossings at each A // vertex. The sign of a crossing depends on whether the other edge // crosses from left to right or right to left. // // This would not be necessary if all calculations were done in exact // arithmetic, because crossings would have strictly alternating signs. // But because we have already snapped the result, some crossing locations // are ambiguous, and GetCrossedVertexIndex() handles this by choosing a // candidate vertex arbitrarily. The end result is that rarely, we may // see two crossings in a row with the same sign. We correct for this by // adding extra output edges that essentially link up the crossings in the // correct (alternating sign) order. Compared to the "correct" behavior, // the only difference is that we have added some extra sibling pairs // (consisting of an edge and its corresponding reverse edge) which do not // affect the result. a_num_crossings.clear(); a_num_crossings.resize(a_vertices.size()); a_isolated.clear(); a_isolated.resize(a_vertices.size()); for (size_t bi = 0; bi < b_input_edges.size(); ++bi) { bool left_to_right = b_input_edges[bi].left_to_right(); int a_index = GetCrossedVertexIndex(a_vertices, b_edges[bi], left_to_right); if (a_index >= 0) { // Keep track of the number of signed crossings (see above). bool is_line = input_dimensions_[b_input_edges[bi].input_id()] == 1; int sign = is_line ? 0 : (left_to_right == invert_b) ? -1 : 1; a_num_crossings[a_index] += sign; // Any polyline or polygon vertex that has at least one crossing but no // adjacent emitted edge may be emitted as an isolated vertex. a_isolated[a_index] = true; } else { // TODO(b/112043775): fix this condition. ABSL_LOG(DFATAL) << "Failed to get crossed vertex index."; } } // Finally, we iterate through the A edge chain, keeping track of the // number of signed crossings as we go along. The "multiplicity" is // defined as the cumulative number of signed crossings, and indicates how // many edges should be output (and in which direction) in order to link // up the edge crossings in the correct order. (The multiplicity is // almost always either 0 or 1 except in very rare cases.) int multiplicity = inside + a_num_crossings[0]; for (size_t ai = 1; ai < a_vertices.size(); ++ai) { if (multiplicity != 0) { a_isolated[ai - 1] = a_isolated[ai] = false; } int edge_count = reverse_a ? -multiplicity : multiplicity; // Output any forward edges required. for (int i = 0; i < edge_count; ++i) { AddEdge(Graph::Edge(a_vertices[ai - 1], a_vertices[ai]), a_input_id); } // Output any reverse edges required. for (int i = edge_count; i < 0; ++i) { AddEdge(Graph::Edge(a_vertices[ai], a_vertices[ai - 1]), a_input_id); } multiplicity += a_num_crossings[ai]; } // Multiplicities other than 0 or 1 can only occur in the edge interior. ABSL_DCHECK(multiplicity == 0 || multiplicity == 1); inside = (multiplicity != 0); // Output any isolated polyline vertices. // TODO(ericv): Only do this if an output layer wants degenerate edges. if (input_dimensions_[a_input_id] != 0) { for (size_t ai = 0; ai < a_vertices.size(); ++ai) { if (a_isolated[ai]) { AddEdge(Graph::Edge(a_vertices[ai], a_vertices[ai]), a_input_id); } } } } } // Given the vertices of the snapped edge chain for an input edge A and the // set of input edges B that cross input edge A, this method gathers all of // the snapped edges of B that are incident to a given snapped vertex of A. // The incident edges for each input edge of B are appended to a separate // output vector. (A and B can refer to either the input edge or the // corresponding snapped edge chain.) void GraphEdgeClipper::GatherIncidentEdges( absl::Span a, int ai, absl::Span b_input_edges, vector* b_edges) const { // Examine all of the edges incident to the given vertex of A. If any edge // comes from a B input edge, append it to the appropriate vector. ABSL_DCHECK_EQ(b_input_edges.size(), b_edges->size()); for (EdgeId e : in_.edge_ids(a[ai])) { InputEdgeId id = input_ids_[e]; auto it = lower_bound(b_input_edges.begin(), b_input_edges.end(), id); if (it != b_input_edges.end() && it->input_id() == id) { auto& edges = (*b_edges)[it - b_input_edges.begin()]; edges.push_back(CrossingGraphEdge(e, ai, false, g_.edge(e).first)); } } for (EdgeId e : out_.edge_ids(a[ai])) { InputEdgeId id = input_ids_[e]; auto it = lower_bound(b_input_edges.begin(), b_input_edges.end(), id); if (it != b_input_edges.end() && it->input_id() == id) { auto& edges = (*b_edges)[it - b_input_edges.begin()]; edges.push_back(CrossingGraphEdge(e, ai, true, g_.edge(e).second)); } } } // Returns the "vertex rank" of the shared vertex associated with the given // CrossingGraphEdge. Recall that graph edges are sorted in input edge order, // and that the rank of an edge is its position in this order (rank_[e]). // VertexRank(e) is defined such that VertexRank(e.src) == rank_[e] and // VertexRank(e.dst) == rank_[e] + 1. Note that the concept of "vertex rank" // is only defined within a single edge chain (since different edge chains can // have overlapping vertex ranks). int GraphEdgeClipper::GetVertexRank(const CrossingGraphEdge& e) const { return rank_[e.id] + !e.outgoing; } // Given an edge chain A that is crossed by another edge chain B (where // "left_to_right" indicates whether B crosses A from left to right), this // method decides which vertex of A the crossing takes place at. The // parameters are the vertices of the A chain ("a") and the set of edges in // the B chain ("b") that are incident to vertices of A. The B chain edges // are sorted in increasing order of (a_index, outgoing) tuple. int GraphEdgeClipper::GetCrossedVertexIndex(absl::Span a, const CrossingGraphEdgeVector& b, bool left_to_right) const { if (a.empty() || b.empty()) { ABSL_LOG(DFATAL) << "GraphEdgeClipper::GetCrossedVertexIndex called with " << a.size() << " vertex ids and " << b.size() << " crossing graph edges."; return -1; } // TODO(b/316414071): Rework this algorithm. // The reason this calculation is tricky is that after snapping, the A and B // chains may meet and separate several times. For example, if B crosses A // from left to right, then B may touch A, make an excursion to the left of // A, come back to A, then make an excursion to the right of A and come back // to A again, like this: // // *--B--*-\ /-*-\ // B-\ /-B B-\ 6 7 8 9 // *--A--*--A--*-A,B-*--A--*--A--*-A,B-*--A--*--A--*-A,B-* // 0 1 2 3 4 5 \-B B-/ // \-*-/ // // (where "*" is a vertex, and "A" and "B" are edge labels). Note that B // may also follow A for one or more edges whenever they touch (e.g. between // vertices 2 and 3). In this case the only vertices of A where the // crossing could take place are 5 and 6, i.e. after all excursions of B to // the left of A, and before all excursions of B to the right of A. // // Other factors to consider are that the portion of B before and/or after // the crossing may be degenerate, and some or all of the B edges may be // reversed relative to the A edges. // First, check whether edge A is degenerate. int n = a.size(); if (n == 1) return 0; // If edge chain B is incident to only one vertex of A, we're done. if (b[0].a_index == b.back().a_index) return b[0].a_index; // Determine whether the B chain visits the first and last vertices that it // shares with the A chain in the same order or the reverse order. This is // only needed to implement one special case (see below). bool b_reversed = GetVertexRank(b[0]) > GetVertexRank(b.back()); // Examine each incident B edge and use it to narrow the range of positions // where the crossing could occur in the B chain. Vertex positions are // represented as a range [lo, hi] of vertex ranks in the B chain (see // GetVertexRank). // // Note that if an edge of B is incident to the first or last vertex of A, // we can't test which side of the A chain it is on. (An s2pred::Sign test // doesn't work; e.g. if the B edge is XY and the first edge of A is YZ, // then snapping can change the sign of XYZ while maintaining topological // guarantees.) There can be up to 4 such edges (one incoming and one // outgoing edge at each endpoint of A). Two of these edges logically // extend past the end of the A chain and place no restrictions on the // crossing vertex. The other two edges define the ends of the subchain // where B shares vertices with A. We save these edges in order to handle a // special case (see below). int lo = -1, hi = order_.size(); // Vertex ranks of acceptable crossings EdgeId b_first = -1, b_last = -1; // "b" subchain connecting "a" endpoints for (const auto& e : b) { int ai = e.a_index; if (ai == 0) { if (e.outgoing != b_reversed && e.dst != a[1]) b_first = e.id; } else if (ai == n - 1) { if (e.outgoing == b_reversed && e.dst != a[n - 2]) b_last = e.id; } else { // This B edge is incident to an interior vertex of the A chain. First // check whether this edge is identical (or reversed) to an edge in the // A chain, in which case it does not create any restrictions. if (e.dst == a[ai - 1] || e.dst == a[ai + 1]) continue; // Otherwise we can test which side of the A chain the edge lies on. bool on_left = s2pred::OrderedCCW(g_.vertex(a[ai + 1]), g_.vertex(e.dst), g_.vertex(a[ai - 1]), g_.vertex(a[ai])); // Every B edge that is incident to an interior vertex of the A chain // places some restriction on where the crossing vertex could be. if (left_to_right == on_left) { // This is a pre-crossing edge, so the crossing cannot be before the // destination vertex of this edge. (For example, the input B edge // crosses the input A edge from left to right and this edge of the B // chain is to the left of the A chain.) lo = max(lo, rank_[e.id] + 1); } else { // This is a post-crossing edge, so the crossing cannot be after the // source vertex of this edge. hi = min(hi, rank_[e.id]); } } } // There is one special case. If a subchain of B connects the first and // last vertices of A, then together with the edges of A this forms a loop // whose orientation can be tested to determine whether B is on the left or // right side of A. This is only possible (and only necessary) if the B // subchain does not include any interior vertices of A, since otherwise the // B chain might cross from one side of A to the other. // // Note that it would be possible to avoid this test in some situations by // checking whether either endpoint of the A chain has two incident B edges, // in which case we could check which side of the B chain the A edge is on // and use this to limit the possible crossing locations. if (b_first >= 0 && b_last >= 0) { // Swap the edges if necessary so that they are in B chain order. if (b_reversed) swap(b_first, b_last); // The B subchain connects the first and last vertices of A. We test // whether the chain includes any interior vertices of A by iterating // through the incident B edges again, looking for ones that belong to // the B subchain and are not incident to the first or last vertex of A. bool has_interior_vertex = false; for (const auto& e : b) { if (e.a_index > 0 && e.a_index < n - 1 && rank_[e.id] >= rank_[b_first] && rank_[e.id] <= rank_[b_last]) { has_interior_vertex = true; break; } } if (!has_interior_vertex) { // The B subchain is not incident to any interior vertex of A. bool on_left = EdgeChainOnLeft(a, b_first, b_last); if (left_to_right == on_left) { lo = max(lo, rank_[b_last] + 1); } else { hi = min(hi, rank_[b_first]); } } } // Otherwise we choose the smallest shared VertexId in the acceptable range, // in order to ensure that both chains choose the same crossing vertex. int best = -1; ABSL_DCHECK_LE(lo, hi); for (const auto& e : b) { int ai = e.a_index; int vrank = GetVertexRank(e); if (vrank >= lo && vrank <= hi && (best < 0 || a[ai] < a[best])) { best = ai; } } return best; } // Given edge chains A and B that form a loop (after possibly reversing the // direction of chain B), returns true if chain B is to the left of chain A. // Chain A is given as a sequence of vertices, while chain B is specified as // the first and last edges of the chain. bool GraphEdgeClipper::EdgeChainOnLeft(absl::Span a, EdgeId b_first, EdgeId b_last) const { // TODO(b/317065708): Rather than collecting all the vertices in a list, // accumulate the angle. // Gather all the interior vertices of the B subchain. vector loop; for (int i = rank_[b_first]; i < rank_[b_last]; ++i) { loop.push_back(g_.edge(order_[i]).second); } // Possibly reverse the chain so that it forms a loop when "a" is appended. if (g_.edge(b_last).second != a[0]) std::reverse(loop.begin(), loop.end()); loop.insert(loop.end(), a.begin(), a.end()); // Duplicate the first two vertices to simplify vertex indexing. for (int j = 0; j < 2; j++) { loop.insert(loop.end(), *(loop.begin() + j)); } // Now B is to the left of A if and only if the loop is counterclockwise. double sum = 0; for (size_t i = 2; i < loop.size(); ++i) { sum += S2::TurnAngle(g_.vertex(loop[i - 2]), g_.vertex(loop[i - 1]), g_.vertex(loop[i])); } return sum > 0; } // Given a set of clipping instructions encoded as a set of intersections // between input edges, EdgeClippingLayer determines which graph edges // correspond to clipped portions of input edges and removes them. It // assembles the remaining edges into a new S2Builder::Graph and passes the // result to the given output layer or layers for assembly. class EdgeClippingLayer : public S2Builder::Layer { public: EdgeClippingLayer(const vector>* layers, const vector* input_dimensions, const InputEdgeCrossings* input_crossings, S2MemoryTracker::Client* tracker) : layers_(*layers), input_dimensions_(*input_dimensions), input_crossings_(*input_crossings), tracker_(tracker) {} // Layer interface: GraphOptions graph_options() const override; void Build(const Graph& g, S2Error* absl_nonnull error) override; private: const vector>& layers_; const vector& input_dimensions_; const InputEdgeCrossings& input_crossings_; S2MemoryTracker::Client* tracker_; }; GraphOptions EdgeClippingLayer::graph_options() const { // We keep all edges, including degenerate ones, so that we can figure out // the correspondence between input edge crossings and output edge // crossings. return GraphOptions(EdgeType::DIRECTED, DegenerateEdges::KEEP, DuplicateEdges::KEEP, SiblingPairs::KEEP); } void EdgeClippingLayer::Build(const Graph& g, S2Error* absl_nonnull error) { // Data per graph edge: // vector order_; // vector rank_; // vector new_edges; // vector new_input_edge_ids; // Data per graph vertex: // Graph::VertexInMap in_; // Graph::VertexOutMap out_; // // The first and last two vectors above are freed upon GraphEdgeClipper // destruction. There is also a temporary vector "indegree" in // GetInputEdgeChainOrder() but this does not affect peak memory usage. int64_t tmp_bytes = g.num_edges() * (sizeof(EdgeId) + sizeof(int)) + g.num_vertices() * (2 * sizeof(EdgeId)); int64_t final_bytes = g.num_edges() * (sizeof(Graph::Edge) + sizeof(InputEdgeIdSetId)); // The order of the calls below is important. Note that all memory tracked // through this client is automatically untallied upon object destruction. if (!tracker_->Tally(final_bytes) || !tracker_->TallyTemp(tmp_bytes)) { // We don't need to copy memory tracking errors to "error" because this // is already done for us in S2BooleanOperation::Impl::Build(). return; } // The bulk of the work is handled by GraphEdgeClipper. vector new_edges; vector new_input_edge_ids; // Destroy the GraphEdgeClipper immediately to save memory. GraphEdgeClipper(g, input_dimensions_, input_crossings_, &new_edges, &new_input_edge_ids).Run(); // Construct one or more subgraphs from the clipped edges and pass them to // the given output layer(s). We start with a copy of the input graph's // IdSetLexicon because this is necessary in general, even though in this // case it is guaranteed to be empty because no edges have been merged. IdSetLexicon new_input_edge_id_set_lexicon = g.input_edge_id_set_lexicon(); if (layers_.size() == 1) { Graph new_graph = g.MakeSubgraph( layers_[0]->graph_options(), &new_edges, &new_input_edge_ids, &new_input_edge_id_set_lexicon, g.is_full_polygon_predicate(), error, tracker_); if (tracker_->ok()) layers_[0]->Build(new_graph, error); tracker_->Untally(new_edges); tracker_->Untally(new_input_edge_ids); } else { // The Graph objects must be valid until the last Build() call completes, // so we store all of the graph data in arrays with 3 elements. ABSL_DCHECK_EQ(3, layers_.size()); vector layer_edges[3]; vector layer_input_edge_ids[3]; // Separate the edges according to their dimension. for (size_t i = 0; i < new_edges.size(); ++i) { int d = input_dimensions_[new_input_edge_ids[i]]; if (!tracker_->AddSpace(&layer_edges[d], 1)) return; if (!tracker_->AddSpace(&layer_input_edge_ids[d], 1)) return; layer_edges[d].push_back(new_edges[i]); layer_input_edge_ids[d].push_back(new_input_edge_ids[i]); } // Clear variables to save space. if (!tracker_->Clear(&new_edges)) return; if (!tracker_->Clear(&new_input_edge_ids)) return; vector layer_graphs; // No default constructor. layer_graphs.reserve(3); for (int d = 0; d < 3; ++d) { layer_graphs.push_back(g.MakeSubgraph( layers_[d]->graph_options(), &layer_edges[d], &layer_input_edge_ids[d], &new_input_edge_id_set_lexicon, g.is_full_polygon_predicate(), error, tracker_)); if (tracker_->ok()) layers_[d]->Build(layer_graphs[d], error); } for (int d = 0; d < 3; ++d) { tracker_->Untally(layer_edges[d]); tracker_->Untally(layer_input_edge_ids[d]); } } } } // namespace class S2BooleanOperation::Impl { public: explicit Impl(S2BooleanOperation* op) : op_(op), index_crossings_first_region_id_(-1), tracker_(op->options_.memory_tracker()) { } bool Build(S2Error* absl_nonnull error); private: class CrossingIterator; class CrossingProcessor; using ShapeEdge = s2shapeutil::ShapeEdge; using ShapeEdgeId = s2shapeutil::ShapeEdgeId; // An IndexCrossing represents a pair of intersecting S2ShapeIndex edges // ("a_edge" and "b_edge"). We store all such intersections because the // algorithm needs them twice, once when processing the boundary of region A // and once when processing the boundary of region B. struct IndexCrossing { ShapeEdgeId a, b; // True if S2::CrossingSign(a_edge, b_edge) > 0. uint32_t is_interior_crossing : 1; // True if "a_edge" crosses "b_edge" from left to right. Undefined if // is_interior_crossing is false. uint32_t left_to_right : 1; // Equal to S2::VertexCrossing(a_edge, b_edge). Undefined if "a_edge" and // "b_edge" do not share exactly one vertex or either edge is degenerate. uint32_t is_vertex_crossing : 1; // All flags are "false" by default. IndexCrossing(ShapeEdgeId _a, ShapeEdgeId _b) : a(_a), b(_b), is_interior_crossing(false), left_to_right(false), is_vertex_crossing(false) { } friend bool operator==(const IndexCrossing& x, const IndexCrossing& y) { return x.a == y.a && x.b == y.b; } friend bool operator<(const IndexCrossing& x, const IndexCrossing& y) { // The compiler (2017) doesn't optimize the following as well: // return x.a < y.a || (x.a == y.a && x.b < y.b); if (x.a.shape_id < y.a.shape_id) return true; if (y.a.shape_id < x.a.shape_id) return false; if (x.a.edge_id < y.a.edge_id) return true; if (y.a.edge_id < x.a.edge_id) return false; if (x.b.shape_id < y.b.shape_id) return true; if (y.b.shape_id < x.b.shape_id) return false; return x.b.edge_id < y.b.edge_id; } }; using IndexCrossings = vector; class MemoryTracker : public S2MemoryTracker::Client { public: using S2MemoryTracker::Client::Client; // Used to track memory used by CrossingProcessor::source_id_map_. (The // type is a template parameter so that SourceIdMap can be private.) template bool TallySourceIdMap(int num_entries) { int64_t delta_bytes = num_entries * GetBtreeMinBytesPerEntry(); source_id_map_bytes_ += delta_bytes; return Tally(delta_bytes); } // Used to clear CrossingProcessor::source_id_map_ and update the tracked // memory usage accordingly. template bool ClearSourceIdMap(T* source_id_map) { source_id_map->clear(); Tally(-source_id_map_bytes_); source_id_map_bytes_ = 0; return ok(); } private: // The amount of memory used by CrossingProcessor::source_id_map_. int64_t source_id_map_bytes_ = 0; }; bool is_boolean_output() const { return op_->result_empty_ != nullptr; } // All of the methods below support "early exit" in the case of boolean // results by returning "false" as soon as the result is known to be // non-empty. bool AddBoundary(int a_region_id, bool invert_a, bool invert_b, bool invert_result, absl::Span a_chain_starts, CrossingProcessor* cp); bool GetChainStarts(int a_region_id, bool invert_a, bool invert_b, bool invert_result, CrossingProcessor* cp, vector* chain_starts); bool ProcessIncidentEdges(const ShapeEdge& a, S2ContainsPointQuery* query, CrossingProcessor* cp); static bool HasInterior(const S2ShapeIndex& index); bool AddIndexCrossing(const ShapeEdge& a, const ShapeEdge& b, bool is_interior, IndexCrossings* crossings); bool InitIndexCrossings(int region_id); bool AddBoundaryPair(bool invert_a, bool invert_b, bool invert_result, CrossingProcessor* cp); bool AreRegionsIdentical() const; bool BuildOpType(OpType op_type); bool IsFullPolygonResult(const S2Builder::Graph& g, S2Error* absl_nonnull error) const; bool IsFullPolygonUnion(const S2ShapeIndex& a, const S2ShapeIndex& b) const; bool IsFullPolygonIntersection(const S2ShapeIndex& a, const S2ShapeIndex& b) const; bool IsFullPolygonDifference(const S2ShapeIndex& a, const S2ShapeIndex& b) const; bool IsFullPolygonSymmetricDifference(const S2ShapeIndex& a, const S2ShapeIndex& b) const; void DoBuild(S2Error* absl_nonnull error); // A bit mask representing all six faces of the S2 cube. static constexpr uint8_t kAllFacesMask = 0x3f; S2BooleanOperation* op_; // The S2Builder options used to construct the output. S2Builder::Options builder_options_; // The S2Builder used to construct the output. Note that the S2Builder // object is created only when is_boolean_output() is false. unique_ptr builder_; // A vector specifying the dimension of each edge added to S2Builder. vector input_dimensions_; // The set of all input edge crossings, which is used by EdgeClippingLayer // to construct the clipped output polygon. InputEdgeCrossings input_crossings_; // kSentinel is a sentinel value used to mark the end of vectors. static const ShapeEdgeId kSentinel; // A vector containing all pairs of crossing edges from the two input // regions (including edge pairs that share a common vertex). The first // element of each pair is an edge from "index_crossings_first_region_id_", // while the second element of each pair is an edge from the other region. IndexCrossings index_crossings_; // Indicates that the first element of each crossing edge pair in // "index_crossings_" corresponds to an edge from the given region. // This field is negative if index_crossings_ has not been computed yet. int index_crossings_first_region_id_; // Temporary storage used in GetChainStarts(), declared here to avoid // repeatedly allocating memory. IndexCrossings tmp_crossings_; // An object to track the memory usage of this class. MemoryTracker tracker_; }; const s2shapeutil::ShapeEdgeId S2BooleanOperation::Impl::kSentinel( std::numeric_limits::max(), 0); // A helper class for iterating through the edges from region B that cross a // particular edge from region A. It caches information from the current // shape, chain, and edge so that it doesn't need to be looked up repeatedly. // Typical usage: // // void SomeFunction(ShapeEdgeId a_id, CrossingIterator *it) { // // Iterate through the edges that cross edge "a_id". // for (; !it->Done(a_id); it->Next()) { // ... use it->b_shape(), it->b_edge(), etc ... // } class S2BooleanOperation::Impl::CrossingIterator { public: // Creates an iterator over crossing edge pairs (a, b) where "b" is an edge // from "b_index". "crossings_complete" indicates that "crossings" contains // all edge crossings between the two regions (rather than a subset). CrossingIterator(const S2ShapeIndex* b_index, const IndexCrossings* crossings, bool crossings_complete) : b_index_(*b_index), it_(crossings->begin()), b_shape_id_(-1), crossings_complete_(crossings_complete) { Update(); } void Next() { ++it_; Update(); } bool Done(ShapeEdgeId id) const { return a_id() != id; } // True if all edge crossings are available (see above). bool crossings_complete() const { return crossings_complete_; } // True if this crossing occurs at a point interior to both edges. bool is_interior_crossing() const { return it_->is_interior_crossing; } // Equal to S2::VertexCrossing(a_edge, b_edge), provided that a_edge and // b_edge have exactly one vertex in common and neither edge is degenerate. bool is_vertex_crossing() const { return it_->is_vertex_crossing; } // True if a_edge crosses b_edge from left to right (for interior crossings). bool left_to_right() const { return it_->left_to_right; } ShapeEdgeId a_id() const { return it_->a; } ShapeEdgeId b_id() const { return it_->b; } const S2ShapeIndex& b_index() const { return b_index_; } const S2Shape& b_shape() const { return *b_shape_; } int b_dimension() const { return b_dimension_; } int b_shape_id() const { return b_shape_id_; } int b_edge_id() const { return b_id().edge_id; } S2Shape::Edge b_edge() const { return b_shape_->edge(b_edge_id()); // Opportunity to cache this. } // Information about the chain to which an edge belongs. struct ChainInfo { int chain_id; // chain id int start; // starting edge id int limit; // limit edge id }; // Returns a description of the chain to which the current B edge belongs. const ChainInfo& b_chain_info() const { if (b_info_.chain_id < 0) { b_info_.chain_id = b_shape().chain_position(b_edge_id()).chain_id; auto chain = b_shape().chain(b_info_.chain_id); b_info_.start = chain.start; b_info_.limit = chain.start + chain.length; } return b_info_; } private: // Updates information about the B shape whenever it changes. void Update() { if (a_id() != kSentinel && b_id().shape_id != b_shape_id_) { b_shape_id_ = b_id().shape_id; b_shape_ = b_index_.shape(b_shape_id_); b_dimension_ = b_shape_->dimension(); b_info_.chain_id = -1; // Computed on demand. } } const S2ShapeIndex& b_index_; IndexCrossings::const_iterator it_; const S2Shape* b_shape_; int b_shape_id_; int b_dimension_; mutable ChainInfo b_info_; // Computed on demand. bool crossings_complete_; }; // CrossingProcessor is a helper class that processes all the edges from one // region that cross a specific edge of the other region. It outputs the // appropriate edges to an S2Builder, and outputs other information required // by GraphEdgeClipper to the given vectors. class S2BooleanOperation::Impl::CrossingProcessor { public: // Prepares to build output for the given polygon and polyline boundary // models. Edges are emitted to "builder", while other auxiliary data is // appended to the given vectors. // // If a predicate is being evaluated (i.e., we do not need to construct the // actual result), then "builder" and the various output vectors should all // be nullptr. CrossingProcessor(const PolygonModel& polygon_model, const PolylineModel& polyline_model, bool polyline_loops_have_boundaries, S2Builder* builder, vector* input_dimensions, InputEdgeCrossings* input_crossings, MemoryTracker* tracker) : polygon_model_(polygon_model), polyline_model_(polyline_model), polyline_loops_have_boundaries_(polyline_loops_have_boundaries), builder_(builder), input_dimensions_(input_dimensions), input_crossings_(input_crossings), tracker_(tracker), prev_inside_(false) {} // Starts processing edges from the given region. "invert_a", "invert_b", // and "invert_result" indicate whether region A, region B, and/or the // result should be inverted, which allows operations such as union and // difference to be implemented. For example, union is ~(~A & ~B). // // This method should be called in pairs, once to process the edges from // region A and once to process the edges from region B. void StartBoundary(int a_region_id, bool invert_a, bool invert_b, bool invert_result); // Starts processing edges from the given shape. void StartShape(const S2Shape* a_shape); // Starts processing edges from the given chain. void StartChain(int chain_id, S2Shape::Chain chain, bool inside); // Processes the given edge "a_id". "it" should be positioned to the set of // edges from the other region that cross "a_id" (if any). // // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool ProcessEdge(ShapeEdgeId a_id, CrossingIterator* it); // This method should be called after each pair of calls to StartBoundary. // (The only operation that processes more than one pair of boundaries is // SYMMETRIC_DIFFERENCE, which computes the union of A-B and B-A.) // // Resets the state of the CrossingProcessor. void DoneBoundaryPair(); // Indicates whether the point being processed along the current edge chain // is in the polygonal interior of the opposite region, using semi-open // boundaries. If "invert_b_" is true then this field is inverted. // // This value along with the set of incident edges can be used to compute // whether the opposite region contains this point under any of the // supported boundary models (PolylineModel::CLOSED, etc). bool inside() const { return inside_; } private: // SourceEdgeCrossing represents an input edge that crosses some other // edge; it crosses the edge from left to right iff the second parameter // is "true". using SourceEdgeCrossing = pair; struct EdgeCrossingResult; struct PointCrossingResult; InputEdgeId input_edge_id() const { return input_dimensions_->size(); } // Returns true if the edges on either side of the first vertex of the // current edge have not been emitted. // // REQUIRES: This method is called just after updating "inside_" for "v0". bool is_v0_isolated(ShapeEdgeId a_id) const { return !inside_ && v0_emitted_max_edge_id_ < a_id.edge_id; } // Returns true if "a_id" is the last edge of the current chain, and the // edges on either side of the last vertex have not been emitted (including // the possibility that the chain forms a loop). bool is_chain_last_vertex_isolated(ShapeEdgeId a_id) const { return (a_id.edge_id == chain_limit_ - 1 && !chain_v0_emitted_ && v0_emitted_max_edge_id_ <= a_id.edge_id); } // Returns true if the given polyline edge contains "v0", taking into // account the specified PolylineModel. bool polyline_contains_v0(int edge_id, int chain_start) const { return (polyline_model_ != PolylineModel::OPEN || edge_id > chain_start); } bool is_degenerate(ShapeEdgeId a_id) const { return is_degenerate_hole_.contains(a_id); } void AddCrossing(const SourceEdgeCrossing& crossing) { if (!tracker_->AddSpace(&source_edge_crossings_, 1)) return; source_edge_crossings_.push_back(make_pair(input_edge_id(), crossing)); } void AddInteriorCrossing(const SourceEdgeCrossing& crossing) { // Crossing edges are queued until the S2Builder edge that they are // supposed to be associated with is created (see AddEdge() and // pending_source_edge_crossings_ for details). pending_source_edge_crossings_.push_back(crossing); } void SetClippingState(InputEdgeId parameter, bool state) { AddCrossing(SourceEdgeCrossing(SourceId(parameter), state)); } // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool AddEdge(ShapeEdgeId a_id, const S2Shape::Edge& a, int dimension, int interior_crossings) { if (builder_ == nullptr) return false; // Boolean output. if (interior_crossings > 0) { // Add the edges that cross this edge to the output so that // GraphEdgeClipper can find them. if (!tracker_->AddSpace(&source_edge_crossings_, pending_source_edge_crossings_.size())) { return false; } for (const auto& crossing : pending_source_edge_crossings_) { source_edge_crossings_.push_back(make_pair(input_edge_id(), crossing)); } // Build a map that translates temporary edge ids (SourceId) to // the representation used by EdgeClippingLayer (InputEdgeId). if (!tracker_->TallySourceIdMap(1)) { return false; } SourceId src_id(a_region_id_, a_id.shape_id, a_id.edge_id); source_id_map_[src_id] = input_edge_id(); } // Set the GraphEdgeClipper's "inside" state to match ours. if (inside_ != prev_inside_) SetClippingState(kSetInside, inside_); if (!tracker_->AddSpace(input_dimensions_, 1)) return false; input_dimensions_->push_back(dimension); builder_->AddEdge(a.v0, a.v1); inside_ ^= (interior_crossings & 1); prev_inside_ = inside_; return tracker_->ok(); } // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool AddPointEdge(const S2Point& p, int dimension) { if (builder_ == nullptr) return false; // Boolean output. if (!prev_inside_) SetClippingState(kSetInside, true); if (!tracker_->AddSpace(input_dimensions_, 1)) return false; input_dimensions_->push_back(dimension); builder_->AddEdge(p, p); prev_inside_ = true; return tracker_->ok(); } bool ProcessEdge0(ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it); bool ProcessEdge1(ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it); bool ProcessEdge2(ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it); void SkipCrossings(ShapeEdgeId a_id, CrossingIterator* it); PointCrossingResult ProcessPointCrossings( ShapeEdgeId a_id, const S2Point& a0, CrossingIterator* it) const; EdgeCrossingResult ProcessEdgeCrossings( ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it); bool IsPolylineVertexInside(bool matches_polyline, bool matches_polygon) const; bool IsPolylineEdgeInside(const EdgeCrossingResult& r, bool is_degenerate) const; bool PolylineEdgeContainsVertex(const S2Point& v, const CrossingIterator& it, int dimension) const; // Constructor parameters: PolygonModel polygon_model_; PolylineModel polyline_model_; bool polyline_loops_have_boundaries_; // The output of the CrossingProcessor consists of a subset of the input // edges that are emitted to "builder_", and some auxiliary information // that allows GraphEdgeClipper to determine which segments of those input // edges belong to the output. The auxiliary information consists of the // dimension of each input edge, and set of input edges from the other // region that cross each input edge. S2Builder* builder_; // (nullptr if boolean output was requested) vector* input_dimensions_; InputEdgeCrossings* input_crossings_; MemoryTracker* tracker_; // Fields set by StartBoundary: int a_region_id_, b_region_id_; bool invert_a_, invert_b_, invert_result_; bool is_union_; // True if this is a UNION operation. // Fields set by StartShape: const S2Shape* a_shape_; int a_dimension_; // Fields set by StartChain: int chain_id_; int chain_start_; int chain_limit_; // Fields updated by ProcessEdge: // A temporary representation of input_crossings_ that is used internally // until all necessary edges from *both* polygons have been emitted to the // S2Builder. This field is then converted by DoneBoundaryPair() into // the InputEdgeCrossings format expected by GraphEdgeClipper. // // The reason that we can't construct input_crossings_ directly is that it // uses InputEdgeIds to identify the edges from both polygons, and when we // are processing edges from the first polygon, InputEdgeIds have not yet // been assigned to the second polygon. So instead this field identifies // edges from the first polygon using an InputEdgeId, and edges from the // second polygon using a (region_id, shape_id, edge_id) tuple (i.e., a // SourceId). // // All crossings are represented twice, once to indicate that an edge from // polygon 0 is crossed by an edge from polygon 1, and once to indicate that // an edge from polygon 1 is crossed by an edge from polygon 0. The entries // are sorted lexicographically by their eventual InputEdgeIds except for // GraphEdgeClipper state modifications, which are sorted by the first // InputEdgeId only. using SourceEdgeCrossings = vector>; SourceEdgeCrossings source_edge_crossings_; // A set of edges that cross the current edge being processed by // ProcessEdge() but that have not yet been associated with a particular // S2Builder edge. This is necessary because ProcessEdge can create up to // three S2Builder edges per input edge: one to represent the edge interior, // and up to two more to represent an isolated start and/or end vertex. The // crossing edges must be associated with the S2Builder edge that represents // the edge interior, and they are stored here until that edge is created. vector pending_source_edge_crossings_; // A map that translates from SourceId (the (region_id, shape_id, edge_id) // triple that identifies an S2ShapeIndex edge) to InputEdgeId (the // sequentially increasing numbers assigned to input edges by S2Builder). using SourceIdMap = absl::btree_map; SourceIdMap source_id_map_; // For each edge in region B that defines a degenerate loop (either a point // loop or a sibling pair), indicates whether that loop represents a shell // or a hole. This information is used during the second pass of // AddBoundaryPair() to determine the output for degenerate edges. flat_hash_map is_degenerate_hole_; // Indicates whether the point being processed along the current edge chain // is in the polygonal interior of the opposite region, using semi-open // boundaries. If "invert_b_" is true then this field is inverted. // // Equal to: b_index_.Contains(current point) ^ invert_b_ bool inside_; // The value that "inside_" would have just before the end of the previous // edge added to S2Builder. This value is used to determine whether the // GraphEdgeClipper state needs to be updated when jumping from one edge chain // to another. bool prev_inside_; // The maximum edge id of any edge in the current chain whose v0 vertex has // already been emitted. This is used to determine when an isolated vertex // needs to be emitted, e.g. when two closed polygons share only a vertex. int v0_emitted_max_edge_id_; // True if the first vertex of the current chain has been emitted. This is // used when processing loops in order to determine whether the first/last // vertex of the loop should be emitted as an isolated vertex. bool chain_v0_emitted_; }; // See documentation above. void S2BooleanOperation::Impl::CrossingProcessor::StartBoundary( int a_region_id, bool invert_a, bool invert_b, bool invert_result) { a_region_id_ = a_region_id; b_region_id_ = 1 - a_region_id; invert_a_ = invert_a; invert_b_ = invert_b; invert_result_ = invert_result; is_union_ = invert_b && invert_result; // Specify to GraphEdgeClipper how these edges should be clipped. SetClippingState(kSetReverseA, invert_a != invert_result); SetClippingState(kSetInvertB, invert_b); } // See documentation above. inline void S2BooleanOperation::Impl::CrossingProcessor::StartShape( const S2Shape* a_shape) { a_shape_ = a_shape; a_dimension_ = a_shape->dimension(); } // See documentation above. inline void S2BooleanOperation::Impl::CrossingProcessor::StartChain( int chain_id, S2Shape::Chain chain, bool inside) { chain_id_ = chain_id; chain_start_ = chain.start; chain_limit_ = chain.start + chain.length; inside_ = inside; v0_emitted_max_edge_id_ = chain.start - 1; // No edges emitted yet. chain_v0_emitted_ = false; } // See documentation above. bool S2BooleanOperation::Impl::CrossingProcessor::ProcessEdge( ShapeEdgeId a_id, CrossingIterator* it) { // chain_edge() is faster than edge() when there are multiple chains. auto a = a_shape_->chain_edge(chain_id_, a_id.edge_id - chain_start_); if (a_dimension_ == 0) { return ProcessEdge0(a_id, a, it); } else if (a_dimension_ == 1) { return ProcessEdge1(a_id, a, it); } else { ABSL_DCHECK_EQ(2, a_dimension_); return ProcessEdge2(a_id, a, it); } } // PointCrossingResult describes the relationship between a point from region A // and a set of crossing edges from region B. For example, "matches_polygon" // indicates whether a polygon vertex from region B matches the given point. struct S2BooleanOperation::Impl::CrossingProcessor::PointCrossingResult { PointCrossingResult() : matches_point(false), matches_polyline(false), matches_polygon(false) { } // Note that "matches_polyline" is true only if the point matches a polyline // vertex of B *and* the polyline contains that vertex, whereas // "matches_polygon" is true if the point matches any polygon vertex. bool matches_point; // Matches point. bool matches_polyline; // Matches contained polyline vertex. bool matches_polygon; // Matches polygon vertex. }; // Processes an edge of dimension 0 (i.e., a point) from region A. // // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::CrossingProcessor::ProcessEdge0( ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it) { ABSL_DCHECK_EQ(a.v0, a.v1); // When a region is inverted, all points and polylines are discarded. if (invert_a_ != invert_result_) { SkipCrossings(a_id, it); return true; } PointCrossingResult r = ProcessPointCrossings(a_id, a.v0, it); // "contained" indicates whether the current point is inside the polygonal // interior of the opposite region, using semi-open boundaries. bool contained = inside_ ^ invert_b_; if (r.matches_polygon && polygon_model_ != PolygonModel::SEMI_OPEN) { contained = (polygon_model_ == PolygonModel::CLOSED); } if (r.matches_polyline) contained = true; // The output of UNION includes duplicate values, so ensure that points are // not suppressed by other points. if (r.matches_point && !is_union_) contained = true; // Test whether the point is contained after region B is inverted. if (contained == invert_b_) return true; // Don't exit early. return AddPointEdge(a.v0, 0); } // Skip any crossings that were not needed to determine the result. inline void S2BooleanOperation::Impl::CrossingProcessor::SkipCrossings( ShapeEdgeId a_id, CrossingIterator* it) { while (!it->Done(a_id)) it->Next(); } // Returns a summary of the relationship between a point from region A and // a set of crossing edges from region B (see PointCrossingResult). S2BooleanOperation::Impl::CrossingProcessor::PointCrossingResult S2BooleanOperation::Impl::CrossingProcessor::ProcessPointCrossings( ShapeEdgeId a_id, const S2Point& a0, CrossingIterator* it) const { PointCrossingResult r; for (; !it->Done(a_id); it->Next()) { if (it->b_dimension() == 0) { r.matches_point = true; } else if (it->b_dimension() == 1) { if (PolylineEdgeContainsVertex(a0, *it, 0)) { r.matches_polyline = true; } } else { r.matches_polygon = true; } } return r; } // EdgeCrossingResult describes the relationship between an edge (a0, a1) from // region A and a set of crossing edges from region B. For example, // "matches_polygon" indicates whether (a0, a1) matches a polygon edge from // region B. struct S2BooleanOperation::Impl::CrossingProcessor::EdgeCrossingResult { // These fields indicate that (a0, a1) exactly matches an edge of B. bool matches_polyline = false; // Matches polyline edge (either direction). // These fields indicate that a B polyline contains the degenerate polyline // (a0, a0) or (a1, a1). (This is identical to whether the B polyline // contains the point a0 or a1 except when the B polyline is degenerate, // since a degenerate polyline VV contains itself in all boundary models but // contains the point V only in the CLOSED polyline model.) bool a0_matches_polyline = false; // B polyline contains (a0, a0) bool a1_matches_polyline = false; // B polyline contains (a1, a1) // These fields indicate that a vertex of (a0, a1) matches a polygon vertex // of B. (Unlike with polylines, the polygon may not contain that vertex.) bool a0_matches_polygon = false; // a0 matches polygon vertex. bool a1_matches_polygon = false; // a1 matches polygon vertex. // When a0 != a1, the first two fields identify any B polygon edge that // exactly matches (a0, a1) or the sibling edge (a1, a0). The third field // identifies any B polygon edge that exactly matches (a0, a0). ShapeEdgeId polygon_match_id; // B polygon edge that matches (a0, a1). ShapeEdgeId sibling_match_id; // B polygon edge that matches (a1, a0). ShapeEdgeId a0_loop_match_id; // B polygon edge that matches (a0, a0). // Convenience functions to test whether a matching edge was found. bool matches_polygon() const { return polygon_match_id.edge_id >= 0; } bool matches_sibling() const { return sibling_match_id.edge_id >= 0; } bool loop_matches_a0() const { return a0_loop_match_id.edge_id >= 0; } // These fields count the number of edge crossings at a0, a1, and the // interior of (a0, a1). int a0_crossings = 0; // Count of polygon crossings at a0. int a1_crossings = 0; // Count of polygon crossings at a1. int interior_crossings = 0; // Count of polygon crossings in edge interior. }; // Processes an edge of dimension 1 (i.e., a polyline edge) from region A. // // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::CrossingProcessor::ProcessEdge1( ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it) { // When a region is inverted, all points and polylines are discarded. if (invert_a_ != invert_result_) { SkipCrossings(a_id, it); return true; } // Evaluate whether the start vertex should belong to the output, in case it // needs to be emitted as an isolated vertex. EdgeCrossingResult r = ProcessEdgeCrossings(a_id, a, it); bool a0_inside = IsPolylineVertexInside(r.a0_matches_polyline, r.a0_matches_polygon); // Test whether the entire polyline edge should be emitted (or not emitted) // because it matches a polyline or polygon edge. bool is_degenerate = (a.v0 == a.v1); inside_ ^= (r.a0_crossings & 1); if (inside_ != IsPolylineEdgeInside(r, is_degenerate)) { inside_ ^= true; // Invert the inside_ state. ++r.a1_crossings; // Restore the correct (semi-open) state later. } // If neither edge adjacent to v0 was emitted, and this polyline contains // v0, and the other region contains v0, then emit an isolated vertex. if (!polyline_loops_have_boundaries_ && a_id.edge_id == chain_start_ && a.v0 == a_shape_->chain_edge(chain_id_, chain_limit_ - chain_start_ - 1).v1) { // This is the first vertex of a polyline loop, so we can't decide if it // is isolated until we process the last polyline edge. chain_v0_emitted_ = inside_; } else if (is_v0_isolated(a_id) && !is_degenerate && polyline_contains_v0(a_id.edge_id, chain_start_) && a0_inside) { if (!AddPointEdge(a.v0, 1)) return false; } // Test whether the entire edge or any part of it belongs to the output. if (inside_ || r.interior_crossings > 0) { // Note: updates "inside_" to correspond to the state just before a1. if (!AddEdge(a_id, a, 1 /*dimension*/, r.interior_crossings)) { return false; } } // Remember whether the edge portion just before "a1" was emitted, so that // we can decide whether "a1" need to be emitted as an isolated vertex. if (inside_) v0_emitted_max_edge_id_ = a_id.edge_id + 1; // Verify that edge crossings are being counted correctly. inside_ ^= (r.a1_crossings & 1); if (it->crossings_complete()) { ABSL_DCHECK_EQ(S2ContainsPointQuery(&it->b_index()).Contains(a.v1), inside_ ^ invert_b_); } // Special case to test whether the last vertex of a polyline should be // emitted as an isolated vertex. if (it->crossings_complete() && !is_degenerate && is_chain_last_vertex_isolated(a_id) && (polyline_model_ == PolylineModel::CLOSED || (!polyline_loops_have_boundaries_ && a.v1 == a_shape_->chain_edge(chain_id_, chain_start_).v0)) && IsPolylineVertexInside(r.a1_matches_polyline, r.a1_matches_polygon)) { if (!AddPointEdge(a.v1, 1)) return false; } return true; } // Returns true if the current point being processed (which must be a polyline // vertex) is contained by the opposite region (after inversion if "invert_b_" // is true). "matches_polyline" and "matches_polygon" indicate whether the // vertex matches a polyline/polygon vertex of the opposite region. bool S2BooleanOperation::Impl::CrossingProcessor::IsPolylineVertexInside( bool matches_polyline, bool matches_polygon) const { // Initially "contained" indicates whether the current point is inside the // polygonal interior of region B using semi-open boundaries. bool contained = inside_ ^ invert_b_; // For UNION the output includes duplicate polylines. The test below // ensures that isolated polyline vertices are not suppressed by other // polyline vertices in the output. if (matches_polyline && !is_union_) { contained = true; } else if (matches_polygon && polygon_model_ != PolygonModel::SEMI_OPEN) { contained = (polygon_model_ == PolygonModel::CLOSED); } // Finally, invert the result if the opposite region should be inverted. return contained ^ invert_b_; } // Returns true if the current polyline edge is contained by the opposite // region (after inversion if "invert_b_" is true). inline bool S2BooleanOperation::Impl::CrossingProcessor::IsPolylineEdgeInside( const EdgeCrossingResult& r, bool is_degenerate) const { // Initially "contained" indicates whether the current point (just past a0) // is inside the polygonal interior of region B using semi-open boundaries. bool contained = inside_ ^ invert_b_; // Note that if r.matches_polyline and is_union_ is true, then "contained" // will be false (unless there is also a matching polygon edge) since // polyline edges are not allowed in the interior of B. In this case we // leave "contained" as false since it causes both matching edges to be // emitted. if (r.matches_polyline && !is_union_) { contained = true; } else if (is_degenerate) { // First allow the polygon boundary model to override the semi-open rules. // Note that a polygon vertex (dimension 2) is considered to completely // contain degenerate OPEN and SEMI_OPEN polylines (dimension 1) even // though the latter do not contain any points. This is because dimension // 2 points are considered to be a strict superset of dimension 1 points. if (polygon_model_ != PolygonModel::SEMI_OPEN && r.a0_matches_polygon) { contained = (polygon_model_ == PolygonModel::CLOSED); } // Note that r.a0_matches_polyline is true if and only if some B polyline // contains the degenerate polyline (a0, a0). if (r.a0_matches_polyline && !is_union_) contained = true; } else if (r.matches_polygon()) { // In the SEMI_OPEN model, polygon sibling pairs cancel each other and // have no effect on point or edge containment. if (!(polygon_model_ == PolygonModel::SEMI_OPEN && r.matches_sibling())) { contained = (polygon_model_ != PolygonModel::OPEN); } } else if (r.matches_sibling()) { contained = (polygon_model_ == PolygonModel::CLOSED); } // Finally, invert the result if the opposite region should be inverted. return contained ^ invert_b_; } // Processes an edge of dimension 2 (i.e., a polygon edge) from region A. // // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::CrossingProcessor::ProcessEdge2( ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it) { // Whenever the two regions contain the same edge, or opposite edges of a // sibling pair, or one region contains a point loop while the other // contains a matching vertex, then in general the result depends on whether // one or both sides represent a degenerate shell or hole. // // In each pass it is easy to determine whether edges in region B represent // degenerate geometry, and if so whether they represent a shell or hole, // since this can be determined from the inside_ state and the // matches_polygon() / matches_sibling() methods of EdgeCrossingResult. // However this information is not readily available for region A. // // We handle this by saving the shell/hole status of each degenerate loop in // region B during the first pass, and deferring the processing of any edges // that meet the criteria above until the second pass. (Note that regions // A,B correspond to regions 0,1 respectively in the first pass whereas they // refer to regions 1,0 respectively in the second pass.) // // The first pass ignores: // - degenerate edges of A that are incident to any edge of B // - non-degenerate edges of A that match or are siblings to an edge of B // // The first pass also records the shell/hole status of: // - degenerate edges of B that are incident to any edge of A // - sibling pairs of B where either edge matches an edge of A // // The second pass processes and perhaps outputs: // - degenerate edges of B that are incident to any edge of A // - non-degenerate edges of B that match or are siblings to an edge of A // // The following flag indicates that we are in the second pass described // above, i.e. that we are emitting any necessary edges that were ignored by // the first pass. bool emit_shared = (a_region_id_ == 1); // Degeneracies such as isolated vertices and sibling pairs can only be // created by intersecting CLOSED polygons or unioning OPEN polygons. bool create_degen = (polygon_model_ == PolygonModel::CLOSED && !invert_a_ && !invert_b_) || (polygon_model_ == PolygonModel::OPEN && invert_a_ && invert_b_); // In addition, existing degeneracies are kept when an open boundary is // subtracted. Note that "keep_degen_b" is only defined for completeness. // It is needed to ensure that the "reverse subtraction operator" (B - A) // preserves degeneracies correctly, however in practice this operator is // only used internally to implement symmetric difference, and in that // situation the preserved degeneracy is always removed from the final // result because it overlaps other geometry. bool keep_degen_a = (polygon_model_ == PolygonModel::OPEN && invert_b_); bool keep_degen_b = (polygon_model_ == PolygonModel::OPEN && invert_a_); EdgeCrossingResult r = ProcessEdgeCrossings(a_id, a, it); ABSL_DCHECK(!r.matches_polyline); // If only one region is inverted, matching/sibling relations are reversed. if (invert_a_ != invert_b_) swap(r.polygon_match_id, r.sibling_match_id); bool is_point = (a.v0 == a.v1); if (!emit_shared) { // Remember the shell/hole status of degenerate B edges that are incident // to any edge of A. (We don't need to do this for vertex a1 since it is // the same as vertex a0 of the following A loop edge.) if (r.loop_matches_a0()) { is_degenerate_hole_[r.a0_loop_match_id] = inside_; if (is_point) return true; } // Point loops are handled identically to points in the semi-open model, // and are easier to process in the first pass (since otherwise in the // r.a0_matches_polygon case we would need to remember the containment // status of the matching vertex). Otherwise we defer processing such // loops to the second pass so that we can distinguish whether the // degenerate edge represents a hole or shell. if (polygon_model_ != PolygonModel::SEMI_OPEN) { if (is_point && r.a0_matches_polygon) return true; } } inside_ ^= (r.a0_crossings & 1); if (!emit_shared) { // Defer processing A edges that match or are siblings to an edge of B. if (r.matches_polygon() || r.matches_sibling()) { // For sibling pairs, also remember their shell/hole status. if (r.matches_polygon() && r.matches_sibling()) { is_degenerate_hole_[r.polygon_match_id] = inside_; is_degenerate_hole_[r.sibling_match_id] = inside_; } ABSL_DCHECK_EQ(r.interior_crossings, 0); inside_ ^= (r.a1_crossings & 1); return true; } } // Remember whether the B geometry represents a sibling pair hole. bool is_b_hole = r.matches_polygon() && r.matches_sibling() && inside_; // At this point, "inside_" indicates whether the initial part of the A edge // is contained by the B geometry using semi-open rules. The following code // implements the various other polygon boundary rules by changing the value // of "inside_" when necessary to indicate whether the current A edge should // be emitted to the output or not. "semi_open_inside" remembers the true // value of "inside_" so that it can be restored later. bool semi_open_inside = inside_; if (is_point) { if (r.loop_matches_a0()) { // Both sides are point loops. The edge is kept only: // - for closed intersection, open union, and open difference; // - if A and B are both holes or both shells. inside_ = create_degen || keep_degen_a || (inside_ == is_degenerate_hole_[r.a0_loop_match_id]); } else if (r.a0_matches_polygon) { // A point loop in A matches a polygon vertex in B. Note that this code // can emit an extra isolated vertex if A represents a point hole, but // this doesn't matter (see comments on the call to AddPointEdge below). if (polygon_model_ != PolygonModel::SEMI_OPEN) { inside_ = create_degen || keep_degen_a; } } } else if (r.matches_polygon()) { if (is_degenerate(a_id)) { // The A edge has a sibling. The edge is kept only: // - for closed intersection, open union, and open difference; // - if the A sibling pair is a hole and the B edge has no sibling; or // - if the B geometry is also a sibling pair and A and B are both // holes or both shells. inside_ = create_degen || keep_degen_a || (!r.matches_sibling() || inside_) == is_degenerate_hole_[a_id]; } else { // Matching edges are kept unless the B geometry is a sibling pair, in // which case it is kept only for closed intersection, open union, and // open difference. if (!r.matches_sibling() || create_degen || keep_degen_b) inside_ = true; } } else if (r.matches_sibling()) { if (is_degenerate(a_id)) { // The A edge has a sibling. The edge is kept only if A is a sibling // pair shell and the operation is closed intersection, open union, or // open difference. inside_ = (create_degen || keep_degen_a) && !is_degenerate_hole_[a_id]; } else { inside_ = create_degen; } } if (inside_ != semi_open_inside) { ++r.a1_crossings; // Restores the correct (semi-open) state later. } // Test whether the first vertex of this edge should be emitted as an // isolated degenerate vertex. This is only needed in the second pass when: // - a0 matches a vertex of the B polygon; // - the initial part of the A edge will not be emitted; and // - the operation is closed intersection or open union, or open difference // and the B geometry is a point loop. // // The logic does not attempt to avoid redundant extra vertices (e.g. the // extra code in ProcessEdge1() that checks whether the vertex is the // endpoint of the preceding emitted edge) since these will be removed during // S2Builder::Graph creation by DegenerateEdges::DISCARD or DISCARD_EXCESS // (which are necessary in any case due to snapping). if (emit_shared && r.a0_matches_polygon && !inside_ && (create_degen || (keep_degen_b && r.loop_matches_a0()))) { if (!AddPointEdge(a.v0, 2)) return false; } // Since we skipped edges in the first pass that only had a sibling pair // match in the B geometry, we sometimes need to emit the sibling pair of an // edge in the second pass. This happens only if: // - the operation is closed intersection, open union, or open difference; // - the A geometry is not a sibling pair (since otherwise we will process // that edge as well); and // - the B geometry is not a sibling pair hole (since then only one edge // should be emitted). if (r.matches_sibling() && (create_degen || keep_degen_b) && !is_degenerate(a_id) && !is_b_hole) { S2Shape::Edge sibling(a.v1, a.v0); if (!AddEdge(r.sibling_match_id, sibling, 2 /*dimension*/, 0)) { return false; } } // Test whether the entire edge or any part of it belongs to the output. if (inside_ || r.interior_crossings > 0) { // Note: updates "inside_" to correspond to the state just before a1. if (!AddEdge(a_id, a, 2 /*dimension*/, r.interior_crossings)) { return false; } } inside_ ^= (r.a1_crossings & 1); // Verify that edge crossings are being counted correctly. if (it->crossings_complete()) { ABSL_DCHECK_EQ(S2ContainsPointQuery(&it->b_index()).Contains(a.v1), inside_ ^ invert_b_); } return true; } // Returns a summary of the relationship between a test edge from region A and // a set of crossing edges from region B (see EdgeCrossingResult). // // NOTE(ericv): We could save a bit of work when matching polygon vertices by // passing in a flag saying whether this information is needed. For example // it is only needed in ProcessEdge2 when (emit_shared && create_degenerate). S2BooleanOperation::Impl::CrossingProcessor::EdgeCrossingResult S2BooleanOperation::Impl::CrossingProcessor::ProcessEdgeCrossings( ShapeEdgeId a_id, const S2Shape::Edge& a, CrossingIterator* it) { pending_source_edge_crossings_.clear(); EdgeCrossingResult r; if (it->Done(a_id)) return r; for (; !it->Done(a_id); it->Next()) { // Polyline and polygon "inside" states are not affected by point geometry. if (it->b_dimension() == 0) continue; S2Shape::Edge b = it->b_edge(); if (it->is_interior_crossing()) { // The crossing occurs in the edge interior. The condition below says // that (1) polyline crossings don't affect the polygon "inside" state, // and (2) subtracting a crossing polyline from a polyline does not // affect its "inside" state. (Note that vertices are still created at // the intersection points.) if (a_dimension_ <= it->b_dimension() && !(invert_b_ != invert_result_ && it->b_dimension() == 1)) { SourceId src_id(b_region_id_, it->b_shape_id(), it->b_edge_id()); AddInteriorCrossing(make_pair(src_id, it->left_to_right())); } r.interior_crossings += (it->b_dimension() == 1) ? 2 : 1; } else if (it->b_dimension() == 1) { // The polygon "inside" state is not affected by polyline geometry. if (a_dimension_ == 2) continue; if ((a.v0 == b.v0 && a.v1 == b.v1) || (a.v0 == b.v1 && a.v1 == b.v0)) { r.matches_polyline = true; } if ((a.v0 == b.v0 || a.v0 == b.v1) && PolylineEdgeContainsVertex(a.v0, *it, 1)) { r.a0_matches_polyline = true; } if ((a.v1 == b.v0 || a.v1 == b.v1) && PolylineEdgeContainsVertex(a.v1, *it, 1)) { r.a1_matches_polyline = true; } } else { ABSL_DCHECK_EQ(2, it->b_dimension()); if (a.v0 == a.v1 || b.v0 == b.v1) { // There are no edge crossings since at least one edge is degenerate. if (a.v0 == b.v0 && a.v0 == b.v1) { r.a0_loop_match_id = it->b_id(); } } else if (a.v0 == b.v0 && a.v1 == b.v1) { ++r.a0_crossings; r.polygon_match_id = it->b_id(); } else if (a.v0 == b.v1 && a.v1 == b.v0) { ++r.a0_crossings; r.sibling_match_id = it->b_id(); } else if (it->is_vertex_crossing()) { if (a.v0 == b.v0 || a.v0 == b.v1) { ++r.a0_crossings; } else { ++r.a1_crossings; } } if (a.v0 == b.v0 || a.v0 == b.v1) { r.a0_matches_polygon = true; } if (a.v1 == b.v0 || a.v1 == b.v1) { r.a1_matches_polygon = true; } } } return r; } // Returns true if the vertex "v" is contained by the polyline edge referred // to by the CrossingIterator "it", taking into account the PolylineModel. // "dimension" is 0 or 1 according to whether "v" should be modeled as a point // or as a degenerate polyline. (This only makes a difference when the // containing polyline is degenerate, since the polyline AA contains itself in // all boundary models but contains the point A only in the CLOSED model.) // // REQUIRES: it.b_dimension() == 1 // REQUIRES: "v" is an endpoint of it.b_edge() bool S2BooleanOperation::Impl::CrossingProcessor::PolylineEdgeContainsVertex( const S2Point& v, const CrossingIterator& it, int dimension) const { ABSL_DCHECK_EQ(1, it.b_dimension()); ABSL_DCHECK(it.b_edge().v0 == v || it.b_edge().v1 == v); ABSL_DCHECK(dimension == 0 || dimension == 1); // Closed polylines contain all their vertices. if (polyline_model_ == PolylineModel::CLOSED) return true; // Note that the code below is structured so that it.b_edge() is not usually // needed (since accessing the edge can be relatively expensive). const auto& b_chain = it.b_chain_info(); int b_edge_id = it.b_edge_id(); // A polyline contains its last vertex only when the polyline is degenerate // (v0 == v1) and "v" is modeled as a degenerate polyline (dimension == 1). // This corresponds to the fact that the polyline AA contains itself in all // boundary models, but contains the point A only in the CLOSED model. if (b_edge_id == b_chain.limit - 1 && v == it.b_edge().v1 && (dimension == 0 || b_edge_id > 0 || v != it.b_edge().v0)) { return false; } // Otherwise all interior vertices are contained. The first polyline // vertex is contained if either the polyline model is not OPEN, or the // polyline forms a loop and polyline_loops_have_boundaries_ is false. if (polyline_contains_v0(b_edge_id, b_chain.start)) return true; if (v != it.b_edge().v0) return true; if (polyline_loops_have_boundaries_) return false; return v == it.b_shape().chain_edge(b_chain.chain_id, b_chain.limit - b_chain.start - 1).v1; } // Translates the temporary representation of crossing edges (SourceId) into // the format expected by EdgeClippingLayer (InputEdgeId). void S2BooleanOperation::Impl::CrossingProcessor::DoneBoundaryPair() { tracker_->AddSpaceExact(input_crossings_, source_edge_crossings_.size()); if (!tracker_->TallySourceIdMap(3)) return; // Add entries that translate the "special" crossings. source_id_map_[SourceId(kSetInside)] = kSetInside; source_id_map_[SourceId(kSetInvertB)] = kSetInvertB; source_id_map_[SourceId(kSetReverseA)] = kSetReverseA; for (const auto& tmp : source_edge_crossings_) { auto it = source_id_map_.find(tmp.second.first); ABSL_DCHECK(it != source_id_map_.end()); input_crossings_->push_back(make_pair( tmp.first, CrossingInputEdge(it->second, tmp.second.second))); } tracker_->Clear(&source_edge_crossings_); tracker_->ClearSourceIdMap(&source_id_map_); } // Clips the boundary of A to the interior of the opposite region B and adds // the resulting edges to the output. Optionally, any combination of region // A, region B, and the result may be inverted, which allows operations such // as union and difference to be implemented. // // Note that when an input region is inverted with respect to the output // (e.g., invert_a != invert_result), all polygon edges are reversed and all // points and polylines are discarded, since the complement of such objects // cannot be represented. (If you want to compute the complement of points // or polylines, you can use S2LaxPolygonShape to represent your geometry as // degenerate polygons instead.) // // This method must be called an even number of times (first to clip A to B // and then to clip B to A), calling DoneBoundaryPair() after each pair. // // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::AddBoundary( int a_region_id, bool invert_a, bool invert_b, bool invert_result, absl::Span a_chain_starts, CrossingProcessor* cp) { const S2ShapeIndex& a_index = *op_->regions_[a_region_id]; const S2ShapeIndex& b_index = *op_->regions_[1 - a_region_id]; if (!InitIndexCrossings(a_region_id)) return false; cp->StartBoundary(a_region_id, invert_a, invert_b, invert_result); // Walk the boundary of region A and build a list of all edge crossings. // We also keep track of whether the current vertex is inside region B. auto chain_start_iter = a_chain_starts.begin(); CrossingIterator next_crossing_iter(&b_index, &index_crossings_, true /*crossings_complete*/); ShapeEdgeId next_id = min(*chain_start_iter, next_crossing_iter.a_id()); while (next_id != kSentinel) { int a_shape_id = next_id.shape_id; const S2Shape& a_shape = *a_index.shape(a_shape_id); cp->StartShape(&a_shape); while (next_id.shape_id == a_shape_id) { // TODO(ericv): Special handling of dimension 0? Can omit most of this // code, including the loop, since all chains are of length 1. int edge_id = next_id.edge_id; S2Shape::ChainPosition chain_position = a_shape.chain_position(edge_id); int chain_id = chain_position.chain_id; S2Shape::Chain chain = a_shape.chain(chain_id); bool start_inside = (next_id == *chain_start_iter); if (start_inside) ++chain_start_iter; cp->StartChain(chain_id, chain, start_inside); int chain_limit = chain.start + chain.length; while (edge_id < chain_limit) { ShapeEdgeId a_id(a_shape_id, edge_id); ABSL_DCHECK(cp->inside() || next_crossing_iter.a_id() == a_id); if (!cp->ProcessEdge(a_id, &next_crossing_iter)) { return false; } if (cp->inside()) { ++edge_id; } else if (next_crossing_iter.a_id().shape_id == a_shape_id && next_crossing_iter.a_id().edge_id < chain_limit) { edge_id = next_crossing_iter.a_id().edge_id; } else { break; } } next_id = min(*chain_start_iter, next_crossing_iter.a_id()); } } return true; } // Returns the first edge of each edge chain from "a_region_id" whose first // vertex is contained by opposite region's polygons (using the semi-open // boundary model). Each input region and the result region are inverted as // specified (invert_a, invert_b, and invert_result) before testing for // containment. The algorithm uses these "chain starts" in order to clip the // boundary of A to the interior of B in an output-sensitive way. // // This method supports "early exit" in the case where a boolean predicate is // being evaluated and the algorithm discovers that the result region will be // non-empty. bool S2BooleanOperation::Impl::GetChainStarts( int a_region_id, bool invert_a, bool invert_b, bool invert_result, CrossingProcessor* cp, vector* chain_starts) { const S2ShapeIndex& a_index = *op_->regions_[a_region_id]; const S2ShapeIndex& b_index = *op_->regions_[1 - a_region_id]; if (is_boolean_output()) { // If boolean output is requested, then we use the CrossingProcessor to // determine whether the first edge of each chain will be emitted to the // output region. This lets us terminate the operation early in many // cases. cp->StartBoundary(a_region_id, invert_a, invert_b, invert_result); } // If region B has no two-dimensional shapes and is not inverted, then by // definition no chain starts are contained. However if boolean output is // requested then we check for containment anyway, since as a side effect we // may discover that the result region is non-empty and terminate the entire // operation early. bool b_has_interior = HasInterior(b_index); if (b_has_interior || invert_b || is_boolean_output()) { S2ContainsPointQuery query(&b_index); int num_shape_ids = a_index.num_shape_ids(); for (int shape_id = 0; shape_id < num_shape_ids; ++shape_id) { const S2Shape* a_shape = a_index.shape(shape_id); if (a_shape == nullptr) continue; // If region A is being subtracted from region B, points and polylines // in region A can be ignored since these shapes never contribute to the // output (they can only remove edges from region B). if (invert_a != invert_result && a_shape->dimension() < 2) continue; if (is_boolean_output()) cp->StartShape(a_shape); int num_chains = a_shape->num_chains(); for (int chain_id = 0; chain_id < num_chains; ++chain_id) { S2Shape::Chain chain = a_shape->chain(chain_id); if (chain.length == 0) continue; ShapeEdge a(shape_id, chain.start, a_shape->chain_edge(chain_id, 0)); bool inside = (b_has_interior && query.Contains(a.v0())) != invert_b; if (inside) { if (!tracker_.AddSpace(chain_starts, 1)) return false; chain_starts->push_back(ShapeEdgeId(shape_id, chain.start)); } if (is_boolean_output()) { cp->StartChain(chain_id, chain, inside); if (!ProcessIncidentEdges(a, &query, cp)) return false; } } } } if (!tracker_.AddSpace(chain_starts, 1)) return false; chain_starts->push_back(kSentinel); return true; } bool S2BooleanOperation::Impl::ProcessIncidentEdges( const ShapeEdge& a, S2ContainsPointQuery* query, CrossingProcessor* cp) { tmp_crossings_.clear(); query->VisitIncidentEdges(a.v0(), [&a, this](const ShapeEdge& b) { return AddIndexCrossing(a, b, false /*is_interior*/, &tmp_crossings_); }); // Fast path for the common case where there are no incident edges. We // return false (terminating early) if the first chain edge will be emitted. if (tmp_crossings_.empty()) { return !cp->inside(); } // Otherwise we invoke the full CrossingProcessor logic to determine whether // the first chain edge will be emitted. if (tmp_crossings_.size() > 1) { std::sort(tmp_crossings_.begin(), tmp_crossings_.end()); // VisitIncidentEdges() should not generate any duplicate values. ABSL_DCHECK( std::adjacent_find(tmp_crossings_.begin(), tmp_crossings_.end()) == tmp_crossings_.end()); } tmp_crossings_.push_back(IndexCrossing(kSentinel, kSentinel)); CrossingIterator next_crossing(&query->index(), &tmp_crossings_, false /*crossings_complete*/); return cp->ProcessEdge(a.id(), &next_crossing); } bool S2BooleanOperation::Impl::HasInterior(const S2ShapeIndex& index) { for (int s = index.num_shape_ids(); --s >= 0; ) { const S2Shape* shape = index.shape(s); if (shape && shape->dimension() == 2) return true; } return false; } inline bool S2BooleanOperation::Impl::AddIndexCrossing( const ShapeEdge& a, const ShapeEdge& b, bool is_interior, IndexCrossings* crossings) { if (!tracker_.AddSpace(crossings, 1)) return false; crossings->push_back(IndexCrossing(a.id(), b.id())); IndexCrossing* crossing = &crossings->back(); if (is_interior) { crossing->is_interior_crossing = true; if (s2pred::Sign(a.v0(), a.v1(), b.v0()) > 0) { crossing->left_to_right = true; } builder_->AddIntersection( S2::GetIntersection(a.v0(), a.v1(), b.v0(), b.v1())); } else { // TODO(ericv): This field isn't used unless one shape is a polygon and // the other is a polyline or polygon, but we don't have the shape // dimension information readily available here. if (S2::VertexCrossing(a.v0(), a.v1(), b.v0(), b.v1())) { crossing->is_vertex_crossing = true; } } return true; // Continue visiting. } // Initialize index_crossings_ to the set of crossing edge pairs such that the // first element of each pair is an edge from "region_id". // // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::InitIndexCrossings(int region_id) { if (region_id == index_crossings_first_region_id_) return true; if (index_crossings_first_region_id_ < 0) { ABSL_DCHECK_EQ(region_id, 0); // For efficiency, not correctness. // TODO(ericv): This would be more efficient if VisitCrossingEdgePairs() // returned the sign (+1 or -1) of the interior crossing, i.e. // "int interior_crossing_sign" rather than "bool is_interior". if (!s2shapeutil::VisitCrossingEdgePairs( *op_->regions_[0], *op_->regions_[1], s2shapeutil::CrossingType::ALL, [this](const ShapeEdge& a, const ShapeEdge& b, bool is_interior) { // For all supported operations (union, intersection, and // difference), if the input edges have an interior crossing // then the output is guaranteed to have at least one edge. if (is_interior && is_boolean_output()) return false; return AddIndexCrossing(a, b, is_interior, &index_crossings_); })) { return false; } if (index_crossings_.size() > 1) { std::sort(index_crossings_.begin(), index_crossings_.end()); index_crossings_.erase( std::unique(index_crossings_.begin(), index_crossings_.end()), index_crossings_.end()); } // Add a sentinel value to simplify the loop logic. tracker_.AddSpace(&index_crossings_, 1); index_crossings_.push_back(IndexCrossing(kSentinel, kSentinel)); index_crossings_first_region_id_ = 0; } if (region_id != index_crossings_first_region_id_) { for (auto& crossing : index_crossings_) { swap(crossing.a, crossing.b); // The following predicates get inverted when the edges are swapped. crossing.left_to_right ^= true; crossing.is_vertex_crossing ^= true; } std::sort(index_crossings_.begin(), index_crossings_.end()); index_crossings_first_region_id_ = region_id; } return tracker_.ok(); } // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::AddBoundaryPair( bool invert_a, bool invert_b, bool invert_result, CrossingProcessor* cp) { // Optimization: if the operation is DIFFERENCE or SYMMETRIC_DIFFERENCE, // it is worthwhile checking whether the two regions are identical (in which // case the output is empty). auto type = op_->op_type_; if (type == OpType::DIFFERENCE || type == OpType::SYMMETRIC_DIFFERENCE) { if (AreRegionsIdentical()) return true; } else if (is_boolean_output()) { // TODO(ericv): When boolean output is requested there are other quick // checks that could be done here, such as checking whether a full cell from // one S2ShapeIndex intersects a non-empty cell of the other S2ShapeIndex. } vector a_starts, b_starts; auto _ = absl::MakeCleanup([&]() { tracker_.Untally(a_starts); tracker_.Untally(b_starts); }); if (!GetChainStarts(0, invert_a, invert_b, invert_result, cp, &a_starts) || !GetChainStarts(1, invert_b, invert_a, invert_result, cp, &b_starts) || !AddBoundary(0, invert_a, invert_b, invert_result, a_starts, cp) || !AddBoundary(1, invert_b, invert_a, invert_result, b_starts, cp)) { return false; } if (!is_boolean_output()) cp->DoneBoundaryPair(); return tracker_.ok(); } // Supports "early exit" in the case of boolean results by returning false // as soon as the result is known to be non-empty. bool S2BooleanOperation::Impl::BuildOpType(OpType op_type) { // CrossingProcessor does the real work of emitting the output edges. CrossingProcessor cp(op_->options_.polygon_model(), op_->options_.polyline_model(), op_->options_.polyline_loops_have_boundaries(), builder_.get(), &input_dimensions_, &input_crossings_, &tracker_); switch (op_type) { case OpType::UNION: // A | B == ~(~A & ~B) return AddBoundaryPair(true, true, true, &cp); case OpType::INTERSECTION: // A & B return AddBoundaryPair(false, false, false, &cp); case OpType::DIFFERENCE: // A - B = A & ~B // // Note that degeneracies are implemented such that the symmetric // operation (-B + A) also produces correct results. This can be tested // by swapping op_->regions[0, 1] and calling AddBoundaryPair(true, // false, false), which computes (~B & A). return AddBoundaryPair(false, true, false, &cp); case OpType::SYMMETRIC_DIFFERENCE: // Compute the union of (A - B) and (B - A). return (AddBoundaryPair(false, true, false, &cp) && AddBoundaryPair(true, false, false, &cp)); } ABSL_LOG(FATAL) << "Invalid S2BooleanOperation::OpType"; return false; } // Returns a bit mask indicating which of the 6 S2 cube faces intersect the // index contents. uint8_t GetFaceMask(const S2ShapeIndex& index) { uint8_t mask = 0; S2ShapeIndex::Iterator it(&index, S2ShapeIndex::BEGIN); while (!it.done()) { int face = it.id().face(); mask |= 1 << face; it.Seek(S2CellId::FromFace(face + 1).range_min()); } return mask; } // Given a polygon edge graph containing only degenerate edges and sibling edge // pairs, the purpose of this function is to decide whether the polygon is empty // or full except for the degeneracies, i.e. whether the degeneracies represent // shells or holes. bool S2BooleanOperation::Impl::IsFullPolygonResult( const S2Builder::Graph& g, S2Error* absl_nonnull error) const { // If there are no edges of dimension 2, the result could be either the // empty polygon or the full polygon. Note that this is harder to determine // than you might think due to snapping. For example, the union of two // non-empty polygons can be empty, because both polygons consist of tiny // loops that are eliminated by snapping. Similarly, even if two polygons // both contain a common point their intersection can still be empty. // // We distinguish empty from full results using two heuristics: // // 1. We compute a bit mask representing the subset of the six S2 cube faces // intersected by each input geometry, and use this to determine if only // one of the two results is possible. (This test is very fast.) Note // that snapping will never cause the result to cover an entire extra // cube face because the maximum allowed snap radius is too small. ABSL_DCHECK_LE(S2Builder::SnapFunction::kMaxSnapRadius().degrees(), 70); // // 2. We compute the area of each input geometry, and use this to bound the // minimum and maximum area of the result. If only one of {0, 4*Pi} is // possible then we are done. If neither is possible then we choose the // one that is closest to being possible (since snapping can change the // result area). Both results are possible only when computing the // symmetric difference of two regions of area 2*Pi each, in which case we // must resort to additional heuristics (see below). // // TODO(ericv): Implement a predicate that uses the results of edge snapping // directly, rather than computing areas. This would not only be much faster // but would also allows all cases to be handled 100% robustly. const S2ShapeIndex& a = *op_->regions_[0]; const S2ShapeIndex& b = *op_->regions_[1]; switch (op_->op_type_) { case OpType::UNION: return IsFullPolygonUnion(a, b); case OpType::INTERSECTION: return IsFullPolygonIntersection(a, b); case OpType::DIFFERENCE: return IsFullPolygonDifference(a, b); case OpType::SYMMETRIC_DIFFERENCE: return IsFullPolygonSymmetricDifference(a, b); default: ABSL_LOG(FATAL) << "Invalid S2BooleanOperation::OpType"; return false; } } bool S2BooleanOperation::Impl::IsFullPolygonUnion( const S2ShapeIndex& a, const S2ShapeIndex& b) const { // See comments in IsFullPolygonResult(). The most common case is that // neither input polygon is empty but the result is empty due to snapping. // The result can be full only if the union of the two input geometries // intersects all six faces of the S2 cube. This test is fast. if ((GetFaceMask(a) | GetFaceMask(b)) != kAllFacesMask) return false; // The union area satisfies: // // max(A, B) <= Union(A, B) <= min(4*Pi, A + B) // // where A, B can refer to a polygon or its area. We then choose the result // that assumes the smallest amount of error. double a_area = S2::GetArea(a), b_area = S2::GetArea(b); double min_area = max(a_area, b_area); double max_area = min(4 * M_PI, a_area + b_area); return min_area > 4 * M_PI - max_area; } bool S2BooleanOperation::Impl::IsFullPolygonIntersection( const S2ShapeIndex& a, const S2ShapeIndex& b) const { // See comments in IsFullPolygonResult(). By far the most common case is // that the result is empty. // The result can be full only if each of the two input geometries // intersects all six faces of the S2 cube. This test is fast. if ((GetFaceMask(a) & GetFaceMask(b)) != kAllFacesMask) return false; // The intersection area satisfies: // // max(0, A + B - 4*Pi) <= Intersection(A, B) <= min(A, B) // // where A, B can refer to a polygon or its area. We then choose the result // that assumes the smallest amount of error. double a_area = S2::GetArea(a), b_area = S2::GetArea(b); double min_area = max(0.0, a_area + b_area - 4 * M_PI); double max_area = min(a_area, b_area); return min_area > 4 * M_PI - max_area; } bool S2BooleanOperation::Impl::IsFullPolygonDifference( const S2ShapeIndex& a, const S2ShapeIndex& b) const { // See comments in IsFullPolygonResult(). By far the most common case is // that the result is empty. // The result can be full only if each cube face is intersected by the first // geometry. (The second geometry is irrelevant, since for example it could // consist of a tiny loop on each S2 cube face.) This test is fast. if (GetFaceMask(a) != kAllFacesMask) return false; // The difference area satisfies: // // max(0, A - B) <= Difference(A, B) <= min(A, 4*Pi - B) // // where A, B can refer to a polygon or its area. We then choose the result // that assumes the smallest amount of error. double a_area = S2::GetArea(a), b_area = S2::GetArea(b); double min_area = max(0.0, a_area - b_area); double max_area = min(a_area, 4 * M_PI - b_area); return min_area > 4 * M_PI - max_area; } bool S2BooleanOperation::Impl::IsFullPolygonSymmetricDifference( const S2ShapeIndex& a, const S2ShapeIndex& b) const { // See comments in IsFullPolygonResult(). By far the most common case is // that the result is empty. // The result can be full only if the union of the two input geometries // intersects all six faces of the S2 cube. This test is fast. uint8_t a_mask = GetFaceMask(a); uint8_t b_mask = GetFaceMask(b); if ((a_mask | b_mask) != kAllFacesMask) return false; // The symmetric difference area satisfies: // // |A - B| <= SymmetricDifference(A, B) <= 4*Pi - |4*Pi - (A + B)| // // where A, B can refer to a polygon or its area. double a_area = S2::GetArea(a), b_area = S2::GetArea(b); double min_area = fabs(a_area - b_area); double max_area = 4 * M_PI - fabs(4 * M_PI - (a_area + b_area)); // Now we choose the result that assumes the smallest amount of error // (min_area in the empty case, and (4*Pi - max_area) in the full case). // However in the case of symmetric difference these two errors may be equal, // meaning that the result is ambiguous. This happens when both polygons have // area 2*Pi. Furthermore, this can happen even when the areas are not // exactly 2*Pi due to snapping and area calculation errors. // // To determine whether the result is ambiguous, we compute a rough estimate // of the maximum expected area error (including errors due to snapping), // using the worst-case error bound for a hemisphere defined by 4 vertices. auto edge_snap_radius = builder_options_.edge_snap_radius(); double hemisphere_area_error = 2 * M_PI * edge_snap_radius.radians() + 40 * DBL_EPSILON; // GetCurvatureMaxError // The following sign is the difference between the error needed for an empty // result and the error needed for a full result. It is negative if an // empty result is possible, positive if a full result is possible, and zero // if both results are possible. double error_sign = min_area - (4 * M_PI - max_area); if (fabs(error_sign) <= hemisphere_area_error) { // Handling the ambiguous case correctly requires a more sophisticated // algorithm (see below), but we can at least handle the simple cases by // testing whether both input geometries intersect all 6 cube faces. If // not, then the result is definitely full. if ((a_mask & b_mask) != kAllFacesMask) return true; // Otherwise both regions have area 2*Pi and intersect all 6 cube faces. // We choose "empty" in this case under the assumption that it is more // likely that the user is computing the difference between two nearly // identical polygons. // // TODO(ericv): Implement a robust algorithm based on examining the edge // snapping results directly, or alternatively add another heuristic (such // as testing containment of random points, or using a larger bit mask in // the tests above, e.g. a 24-bit mask representing all level 1 cells). return false; } return error_sign > 0; } // When subtracting regions, we can save a lot of work by detecting the // relatively common case where the two regions are identical. bool S2BooleanOperation::Impl::AreRegionsIdentical() const { const S2ShapeIndex* a = op_->regions_[0]; const S2ShapeIndex* b = op_->regions_[1]; if (a == b) return true; // If the regions are not identical, we would like to detect that fact as // quickly as possible. In particular we would like to avoid fully decoding // both shapes if they are represented as encoded shape types. // // First we test whether the two geometries have the same dimensions and // chain structure. This can be done without decoding any S2Points. int num_shape_ids = a->num_shape_ids(); if (num_shape_ids != b->num_shape_ids()) return false; for (int s = 0; s < num_shape_ids; ++s) { const S2Shape* a_shape = a->shape(s); const S2Shape* b_shape = b->shape(s); int dimension = a_shape->dimension(); if (dimension != b_shape->dimension()) return false; int num_chains = a_shape->num_chains(); if (num_chains != b_shape->num_chains()) return false; int num_edges = a_shape->num_edges(); if (num_edges != b_shape->num_edges()) return false; if (dimension == 0) { ABSL_DCHECK_EQ(num_edges, num_chains); // All chains are of length 1. continue; } for (int c = 0; c < num_chains; ++c) { S2Shape::Chain a_chain = a_shape->chain(c); S2Shape::Chain b_chain = b_shape->chain(c); ABSL_DCHECK_EQ(a_chain.start, b_chain.start); if (a_chain.length != b_chain.length) return false; } } // Next we test whether both geometries have the same vertex positions. for (int s = 0; s < num_shape_ids; ++s) { const S2Shape* a_shape = a->shape(s); const S2Shape* b_shape = b->shape(s); int num_chains = a_shape->num_chains(); for (int c = 0; c < num_chains; ++c) { S2Shape::Chain a_chain = a_shape->chain(c); for (int i = 0; i < a_chain.length; ++i) { S2Shape::Edge a_edge = a_shape->chain_edge(c, i); S2Shape::Edge b_edge = b_shape->chain_edge(c, i); if (a_edge.v0 != b_edge.v0) return false; if (a_edge.v1 != b_edge.v1) return false; } } // Note that we don't need to test whether both shapes have the same // GetReferencePoint(), because S2Shape requires that the full geometry of // the shape (including its interior) must be derivable from its chains // and edges. This is why the "full loop" exists; see s2shape.h. } return true; } void S2BooleanOperation::Impl::DoBuild(S2Error* absl_nonnull error) { if (!tracker_.ok()) return; builder_options_ = S2Builder::Options(op_->options_.snap_function()); builder_options_.set_intersection_tolerance(S2::kIntersectionError); builder_options_.set_memory_tracker(tracker_.tracker()); if (op_->options_.split_all_crossing_polyline_edges()) { builder_options_.set_split_crossing_edges(true); } // TODO(ericv): Ideally idempotent() should be true, but existing clients // expect vertices closer than the full "snap_radius" to be snapped. builder_options_.set_idempotent(false); if (is_boolean_output()) { // BuildOpType() returns true if and only if the result has no edges. S2Builder::Graph g; // Unused by IsFullPolygonResult() implementation. *op_->result_empty_ = BuildOpType(op_->op_type_) && !IsFullPolygonResult(g, error); return; } builder_ = make_unique(builder_options_); builder_->StartLayer(make_unique( &op_->layers_, &input_dimensions_, &input_crossings_, &tracker_)); // Add a predicate that decides whether a result with no polygon edges should // be interpreted as the empty polygon or the full polygon. builder_->AddIsFullPolygonPredicate( [this](const S2Builder::Graph& g, S2Error* absl_nonnull error) { return IsFullPolygonResult(g, error); }); (void) BuildOpType(op_->op_type_); // Release memory that is no longer needed. if (!tracker_.Clear(&index_crossings_)) return; builder_->Build(error); } bool S2BooleanOperation::Impl::Build(S2Error* absl_nonnull error) { // This wrapper ensures that memory tracking errors are reported. *error = S2Error::Ok(); DoBuild(error); if (!tracker_.ok()) *error = tracker_.error(); return error->ok(); } S2BooleanOperation::Options::Options() : snap_function_(make_unique( S1Angle::Zero())) { } S2BooleanOperation::Options::Options(const SnapFunction& snap_function) : snap_function_(snap_function.Clone()) { } S2BooleanOperation::Options::Options(const Options& options) : snap_function_(options.snap_function_->Clone()), polygon_model_(options.polygon_model_), polyline_model_(options.polyline_model_), polyline_loops_have_boundaries_(options.polyline_loops_have_boundaries_), split_all_crossing_polyline_edges_( options.split_all_crossing_polyline_edges_), precision_(options.precision_), conservative_output_(options.conservative_output_), source_id_lexicon_(options.source_id_lexicon_), memory_tracker_(options.memory_tracker_) { } S2BooleanOperation::Options& S2BooleanOperation::Options::operator=( const Options& options) { snap_function_ = options.snap_function_->Clone(); polygon_model_ = options.polygon_model_; polyline_model_ = options.polyline_model_; polyline_loops_have_boundaries_ = options.polyline_loops_have_boundaries_; split_all_crossing_polyline_edges_ = options.split_all_crossing_polyline_edges_; precision_ = options.precision_; conservative_output_ = options.conservative_output_; source_id_lexicon_ = options.source_id_lexicon_; memory_tracker_ = options.memory_tracker_; return *this; } const SnapFunction& S2BooleanOperation::Options::snap_function() const { return *snap_function_; } void S2BooleanOperation::Options::set_snap_function( const SnapFunction& snap_function) { snap_function_ = snap_function.Clone(); } PolygonModel S2BooleanOperation::Options::polygon_model() const { return polygon_model_; } void S2BooleanOperation::Options::set_polygon_model(PolygonModel model) { polygon_model_ = model; } PolylineModel S2BooleanOperation::Options::polyline_model() const { return polyline_model_; } void S2BooleanOperation::Options::set_polyline_model(PolylineModel model) { polyline_model_ = model; } bool S2BooleanOperation::Options::polyline_loops_have_boundaries() const { return polyline_loops_have_boundaries_; } void S2BooleanOperation::Options::set_polyline_loops_have_boundaries( bool value) { polyline_loops_have_boundaries_ = value; } bool S2BooleanOperation::Options::split_all_crossing_polyline_edges() const { return split_all_crossing_polyline_edges_; } void S2BooleanOperation::Options::set_split_all_crossing_polyline_edges( bool value) { split_all_crossing_polyline_edges_ = value; } Precision S2BooleanOperation::Options::precision() const { return precision_; } bool S2BooleanOperation::Options::conservative_output() const { return conservative_output_; } ValueLexicon* S2BooleanOperation::Options::source_id_lexicon() const { return source_id_lexicon_; } S2MemoryTracker* S2BooleanOperation::Options::memory_tracker() const { return memory_tracker_; } void S2BooleanOperation::Options::set_memory_tracker(S2MemoryTracker* tracker) { memory_tracker_ = tracker; } string_view S2BooleanOperation::OpTypeToString(OpType op_type) { switch (op_type) { case OpType::UNION: return "UNION"; case OpType::INTERSECTION: return "INTERSECTION"; case OpType::DIFFERENCE: return "DIFFERENCE"; case OpType::SYMMETRIC_DIFFERENCE: return "SYMMETRIC DIFFERENCE"; default: return "Unknown OpType"; } } string_view S2BooleanOperation::PolygonModelToString(PolygonModel model) { switch (model) { case PolygonModel::OPEN: return "OPEN"; case PolygonModel::SEMI_OPEN: return "SEMI_OPEN"; case PolygonModel::CLOSED: return "CLOSED"; default: return "Unknown PolygonModel"; } } string_view S2BooleanOperation::PolylineModelToString(PolylineModel model) { switch (model) { case PolylineModel::OPEN: return "OPEN"; case PolylineModel::SEMI_OPEN: return "SEMI_OPEN"; case PolylineModel::CLOSED: return "CLOSED"; default: return "Unknown PolylineModel"; } } S2BooleanOperation::S2BooleanOperation(OpType op_type, const Options& options) : options_(options), op_type_(op_type) {} S2BooleanOperation::S2BooleanOperation(OpType op_type, bool* result_empty, const Options& options) : options_(options), op_type_(op_type), result_empty_(result_empty) { } S2BooleanOperation::S2BooleanOperation(OpType op_type, unique_ptr layer, const Options& options) : options_(options), op_type_(op_type) { layers_.push_back(std::move(layer)); } S2BooleanOperation::S2BooleanOperation( OpType op_type, vector> layers, const Options& options) : options_(options), op_type_(op_type), layers_(std::move(layers)) {} bool S2BooleanOperation::Build(const S2ShapeIndex& a, const S2ShapeIndex& b, S2Error* absl_nonnull error) { regions_[0] = &a; regions_[1] = &b; return Impl(this).Build(error); } bool S2BooleanOperation::IsEmpty( OpType op_type, const S2ShapeIndex& a, const S2ShapeIndex& b, const Options& options) { bool result_empty; S2BooleanOperation op(op_type, &result_empty, options); S2Error error; op.Build(a, b, &error); ABSL_DCHECK(error.ok()); return result_empty; } src/s2/s2boolean_operation.h000066400000000000000000000663761524103652300163310ustar00rootroot00000000000000// Copyright 2017 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_S2BOOLEAN_OPERATION_H_ #define S2_S2BOOLEAN_OPERATION_H_ #include #include #include #include #include "absl/base/nullability.h" #include "absl/log/absl_log.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s2builder.h" #include "s2/s2builder_graph.h" #include "s2/s2builder_layer.h" #include "s2/s2error.h" #include "s2/s2memory_tracker.h" #include "s2/s2shape_index.h" #include "s2/value_lexicon.h" // This class implements boolean operations (intersection, union, difference, // and symmetric difference) for regions whose boundaries are defined by // geodesic edges. // // S2BooleanOperation operates on exactly two input regions at a time. Each // region is represented as an S2ShapeIndex and may contain any number of // points, polylines, and polygons. The region is essentially the union of // these objects, except that polygon interiors must be disjoint from all // other geometry (including other polygon interiors). If the input geometry // for a region does not meet this condition, it can be normalized by // computing its union first. Duplicate polygon edges are not allowed (even // among different polygons), however polylines may have duplicate edges and // may even be self-intersecting. Note that points or polylines are allowed // to coincide with the boundaries of polygons. // // Degeneracies are fully supported. Supported degeneracy types include the // following: // // - Point polylines consisting of a single degenerate edge AA. // // - Point loops consisting of a single vertex A. Such loops may represent // either shells or holes according to whether the loop adds to or // subtracts from the surrounding region of the polygon. // // - Sibling edge pairs of the form {AB, BA}. Such sibling pairs may // represent either shells or holes according to whether they add to or // subtract from the surrounding region. The edges of a sibling pair may // belong to the same polygon loop (e.g. a loop AB) or to different polygon // loops or polygons (e.g. the polygons {ABC, CBD}). // // A big advantage of degeneracy support is that geometry may be simplified // without completely losing small details. For example, if a polygon // representing a land area with many lakes and rivers is simplified using a // tolerance of 1 kilometer, every water feature in the input is guaranteed to // be within 1 kilometer of some water feature in the input (even if some // lakes and rivers are merged and/or reduced to degenerate point or sibling // edge pair holes). Mathematically speaking, degeneracy support allows // geometry to be simplified while guaranteeing that the Hausdorff distance // between the boundaries of the original and simplified geometries is at // most the simplification tolerance. It also allows geometry to be // simplified without changing its dimension, thus preserving boundary // semantics. (Note that the boundary of a polyline ABCD is {A,D}, whereas // the boundary of a degenerate shell ABCDCB is its entire set of vertices and // edges.) // // Points and polyline edges are treated as multisets: if the same point or // polyline edge appears multiple times in the input, it will appear multiple // times in the output. For example, the union of a point with an identical // point consists of two points. This feature is useful for modeling large // sets of points or polylines as a single region while maintaining their // distinct identities, even when the points or polylines intersect each // other. It is also useful for reconstructing polylines that loop back on // themselves (e.g., time series such as GPS tracks). If duplicate geometry // is not desired, it can easily be removed by choosing the appropriate // S2Builder output layer options. // // Self-intersecting polylines can be manipulated without materializing new // vertices at the self-intersection points. This feature is important when // processing polylines with large numbers of self-intersections such as GPS // tracks (e.g., consider the path of a race car in the Indy 500). // // Polylines are always considered to be directed. Polyline edges between the // same pair of vertices are defined to intersect even if the two edges are in // opposite directions. (Undirected polylines can be modeled by specifying // GraphOptions::EdgeType::UNDIRECTED in the S2Builder output layer.) // // The output of each operation is sent to an S2Builder::Layer provided by the // client. This allows clients to build any representation of the geometry // they choose. It also allows the client to do additional postprocessing of // the output before building data structures; for example, the client can // easily discard degeneracies or convert them to another data type. // // The boundaries of polygons and polylines can be modeled as open, semi-open, // or closed. Polyline boundaries are controlled by the PolylineModel class, // whose options are as follows: // // - In the OPEN model, polylines do not contain their first or last vertex // except for one special case: namely, if the polyline forms a loop and // the polyline_loops_have_boundaries() option is set to false, then the // first/last vertex is contained. // // - In the SEMI_OPEN model, polylines contain all vertices except the last. // Therefore if one polyline starts where another polyline stops, the two // polylines do not intersect. // // - In the CLOSED model, polylines contain all of their vertices. // // When multiple polylines are present, they are processed independently and // have no effect on each other. For example, in the OPEN boundary model the // polyline ABC contains the vertex B, while set of polylines {AB, BC} does // not. (If you want to treat the polylines as a union instead, with // boundaries merged according to the "mod 2" rule, this can be achieved by // reassembling the edges into maximal polylines using S2PolylineVectorLayer // with EdgeType::UNDIRECTED, DuplicateEdges::MERGE, and PolylineType::WALK.) // // Polygon boundaries are controlled by the PolygonModel class, which has the // following options: // // - In the OPEN model, polygons do not contain their vertices or edges. // This implies that a polyline that follows the boundary of a polygon will // not intersect it. // // - In the SEMI_OPEN model, polygon point containment is defined such that // if several polygons tile the region around a vertex, then exactly one of // those polygons contains that vertex. Similarly polygons contain all of // their edges, but none of their reversed edges. This implies that a // polyline and polygon edge with the same endpoints intersect if and only // if they are in the same direction. (This rule ensures that if a // polyline is intersected with a polygon and its complement, the two // resulting polylines do not have any edges in common.) // // - In the CLOSED model, polygons contain all their vertices, edges, and // reversed edges. This implies that a polyline that shares an edge (in // either direction) with a polygon is defined to intersect it. Similarly, // this is the only model where polygons that touch at a vertex or along an // edge intersect. // // Note that PolylineModel and PolygonModel are defined as separate classes in // order to allow for possible future extensions. // // Operations between geometry of different dimensions are defined as follows: // // - For UNION, the higher-dimensional shape always wins. For example the // union of a closed polygon A with a polyline B that coincides with the // boundary of A consists only of the polygon A. // // - For INTERSECTION, the lower-dimensional shape always wins. For example, // the intersection of a closed polygon A with a point B that coincides // with a vertex of A consists only of the point B. // // - For DIFFERENCE, higher-dimensional shapes are not affected by // subtracting lower-dimensional shapes. For example, subtracting a point // or polyline from a polygon A yields the original polygon A. This rule // exists because in general, it is impossible to represent the output // using the specified boundary model(s). (Consider subtracting one vertex // from a PolylineModel::CLOSED polyline, or subtracting one edge from a // PolygonModel::CLOSED polygon.) If you want to perform operations like // this, consider representing all boundaries explicitly (topological // boundaries) using OPEN boundary models. Another option for polygons is // to subtract a degenerate loop, which yields a polygon with a degenerate // hole (see S2LaxPolygonShape). // // Note that in the case of Precision::EXACT operations, the above remarks // only apply to the output before snapping. Snapping may cause nearby // distinct edges to become coincident, e.g. a polyline may become coincident // with a polygon boundary. However also note that S2BooleanOperation is // perfectly happy to accept such geometry as input. // // Example usage: // S2ShapeIndex a, b; // Input geometry, e.g. containing polygons. // S2Polygon polygon; // Output geometry. // S2BooleanOperation::Options options; // options.set_snap_function(snap_function); // S2BooleanOperation op(S2BooleanOperation::OpType::INTERSECTION, // std::make_unique(&polygon), // options); // S2Error error; // if (!op.Build(a, b, &error)) { // ABSL_LOG(ERROR) << error; // ... // } // // If the output includes objects of different dimensions, they can be // assembled into different layers with code like this: // // vector points; // vector> polylines; // S2Polygon polygon; // S2BooleanOperation op( // S2BooleanOperation::OpType::UNION, // std::make_unique(&points), // std::make_unique(&polylines), // std::make_unique(&polygon)); class S2BooleanOperation { public: // The supported operation types. enum class OpType : uint8_t { UNION, // Contained by either region. INTERSECTION, // Contained by both regions. DIFFERENCE, // Contained by the first region but not the second. SYMMETRIC_DIFFERENCE // Contained by one region but not the other. }; // Translates OpType to one of the strings above. static absl::string_view OpTypeToString(OpType op_type); // Defines whether polygons are considered to contain their vertices and/or // edges (see definitions above). enum class PolygonModel : uint8_t { OPEN, SEMI_OPEN, CLOSED }; // Translates PolygonModel to one of the strings above. static absl::string_view PolygonModelToString(PolygonModel model); // Defines whether polylines are considered to contain their endpoints // (see definitions above). enum class PolylineModel : uint8_t { OPEN, SEMI_OPEN, CLOSED }; // Translates PolylineModel to one of the strings above. static absl::string_view PolylineModelToString(PolylineModel model); // With Precision::EXACT, the operation is evaluated using the exact input // geometry. Predicates that use this option will produce exact results; // for example, they can distinguish between a polyline that barely // intersects a polygon from one that barely misses it. Constructive // operations (ones that yield new geometry, as opposed to predicates) are // implemented by computing the exact result and then snap rounding it // according to the given snap_function() (see below). This is as close as // it is possible to get to the exact result while requiring that vertex // coordinates have type "double". // // With Precision::SNAPPED, the input regions are snapped together *before* // the operation is evaluated. So for example, two polygons that overlap // slightly will be treated as though they share a common boundary, and // similarly two polygons that are slightly separated from each other will // be treated as though they share a common boundary. Snapped results are // useful for dealing with points, since in S2 the only points that lie // exactly on a polyline or polygon edge are the endpoints of that edge. // // Conceptually, the difference between these two options is that with // Precision::SNAPPED, the inputs are snap rounded (together), whereas with // Precision::EXACT only the result is snap rounded. enum class Precision : uint8_t { EXACT, SNAPPED }; // SourceId identifies an edge from one of the two input S2ShapeIndexes. // It consists of a region id (0 or 1), a shape id within that region's // S2ShapeIndex, and an edge id within that shape. class SourceId { public: SourceId(); SourceId(int region_id, int32_t shape_id, int32_t edge_id); explicit SourceId(int32_t special_edge_id); int region_id() const { return region_id_; } int32_t shape_id() const { return shape_id_; } int32_t edge_id() const { return edge_id_; } // TODO(ericv): Convert to functions, define all 6 comparisons. bool operator==(SourceId other) const; bool operator<(SourceId other) const; private: // TODO(user): Use in-class initializers when C++20 is allowed in // opensource. uint32_t region_id_ : 1; uint32_t shape_id_ : 31; int32_t edge_id_; }; class Options { public: Options(); // Convenience constructor that calls set_snap_function(). explicit Options(const S2Builder::SnapFunction& snap_function); // Specifies the function to be used for snap rounding. // // DEFAULT: s2builderutil::IdentitySnapFunction(S1Angle::Zero()) // - This does no snapping and preserves all input vertices exactly unless // there are crossing edges, in which case the snap radius is increased // to the maximum intersection point error (S2::kIntersectionError). const S2Builder::SnapFunction& snap_function() const; void set_snap_function(const S2Builder::SnapFunction& snap_function); // Defines whether polygons are considered to contain their vertices // and/or edges (see comments above). // // DEFAULT: PolygonModel::SEMI_OPEN PolygonModel polygon_model() const; void set_polygon_model(PolygonModel model); // Defines whether polylines are considered to contain their vertices (see // comments above). // // DEFAULT: PolylineModel::CLOSED PolylineModel polyline_model() const; void set_polyline_model(PolylineModel model); // Specifies whether a polyline loop is considered to have a non-empty // boundary. By default this option is true, meaning that even if the // first and last vertices of a polyline are the same, the polyline is // considered to have a well-defined "start" and "end". For example, if // the polyline boundary model is OPEN then the polyline loop would not // include the start/end vertices. These are the best semantics for most // applications, such as GPS tracks or road network segments. // // If the polyline forms a loop and this option is set to false, then // instead the first and last vertices are considered to represent a // single vertex in the interior of the polyline. In this case the // boundary of the polyline is empty, meaning that the first/last vertex // will be contained by the polyline even if the boundary model is OPEN. // (Note that this option also has a small effect on the CLOSED boundary // model, because the first/last vertices of a polyline loop are // considered to represent one vertex rather than two.) // // The main reason for this option is to implement the "mod 2 union" // boundary semantics of the OpenGIS Simple Features spec. This can be // achieved by making sure that all polylines are constructed using // S2Builder::Graph::PolylineType::WALK (which ensures that all polylines // are as long as possible), and then setting this option to false. // // DEFAULT: true bool polyline_loops_have_boundaries() const; void set_polyline_loops_have_boundaries(bool value); // Specifies that a new vertex should be added whenever a polyline edge // crosses another polyline edge. Note that this can cause the size of // polylines with many self-intersections to increase quadratically. // // If false, new vertices are added only when a polyline from one input // region cross a polyline from the other input region. This allows // self-intersecting input polylines to be modified as little as possible. // // DEFAULT: false bool split_all_crossing_polyline_edges() const; void set_split_all_crossing_polyline_edges(bool value); // Specifies whether the operation should use the exact input geometry // (Precision::EXACT), or whether the two input regions should be snapped // together first (Precision::SNAPPED). // // DEFAULT: Precision::EXACT Precision precision() const; // TODO(b/78590369): Precision.SNAPPED is not yet implemented. // void set_precision(Precision precision); // If true, the input geometry is interpreted as representing nearby // geometry that has been snapped or simplified. It then outputs a // conservative result based on the value of polygon_model() and // polyline_model(). For the most part, this only affects the handling of // degeneracies. // // - If the model is OPEN, the result is as open as possible. For // example, the intersection of two identical degenerate shells is empty // under PolygonModel::OPEN because they could have been disjoint before // snapping. Similarly, two identical degenerate polylines have an // empty intersection under PolylineModel::OPEN. // // - If the model is CLOSED, the result is as closed as possible. In the // case of the DIFFERENCE operation, this is equivalent to evaluating // A - B as Closure(A) - Interior(B). For other operations, it affects // only the handling of degeneracies. For example, the union of two // identical degenerate holes is empty under PolygonModel::CLOSED // (i.e., the hole disappears) because the holes could have been // disjoint before snapping. // // - If the model is SEMI_OPEN, the result is as degenerate as possible. // New degeneracies will not be created, but all degeneracies that // coincide with the opposite region's boundary are retained unless this // would cause a duplicate polygon edge to be created. This model is // is very useful for working with input data that has both positive and // negative degeneracies (i.e., degenerate shells and holes). // // DEFAULT: false bool conservative_output() const; // TODO(b/315152896): Implement support for conservative output. // void set_conservative_output(bool conservative); // If specified, then each output edge will be labelled with one or more // SourceIds indicating which input edge(s) it corresponds to. This // can be useful if your input geometry has additional data that needs to // be propagated from the input to the output (e.g., elevations). // // You can access the labels by using an S2Builder::Layer type that // supports labels, such as S2PolygonLayer. The layer outputs a // "label_set_lexicon" and an "label_set_id" for each edge. You can then // look up the source information for each edge like this: // // for (int32_t label : label_set_lexicon.id_set(label_set_id)) { // const SourceId& src = source_id_lexicon.value(label); // // region_id() specifies which S2ShapeIndex the edge is from (0 or 1). // DoSomething(src.region_id(), src.shape_id(), src.edge_id()); // } // // DEFAULT: nullptr ValueLexicon* source_id_lexicon() const; // TODO(b/314819022): Implement support for source_id_lexicon. // void set_source_id_lexicon(ValueLexicon* source_id_lexicon); // Specifies that internal memory usage should be tracked using the given // S2MemoryTracker. If a memory limit is specified and more more memory // than this is required then an error will be returned. Example usage: // // S2MemoryTracker tracker; // tracker.set_limit(500 << 20); // 500 MB // S2BooleanOperation::Options options; // options.set_memory_tracker(&tracker); // S2BooleanOperation op(..., options); // ... // S2Error error; // if (!op.Build(..., &error)) { // if (error.code() == S2Error::RESOURCE_EXHAUSTED) { // ABSL_LOG(ERROR) << error; // Memory limit exceeded // } // } // // CAVEATS: // // - Memory used by the input S2ShapeIndexes and the output S2Builder // layers is not counted towards the total. // // - While memory tracking is reasonably complete and accurate, it does // not account for every last byte. It is intended only for the // purpose of preventing clients from running out of memory. // // DEFAULT: nullptr (memory tracking disabled) S2MemoryTracker* memory_tracker() const; void set_memory_tracker(S2MemoryTracker* tracker); // Options may be assigned and copied. Options(const Options& options); Options& operator=(const Options& options); private: std::unique_ptr snap_function_; PolygonModel polygon_model_ = PolygonModel::SEMI_OPEN; PolylineModel polyline_model_ = PolylineModel::CLOSED; bool polyline_loops_have_boundaries_ = true; bool split_all_crossing_polyline_edges_ = false; Precision precision_ = Precision::EXACT; bool conservative_output_ = false; ValueLexicon* source_id_lexicon_ = nullptr; S2MemoryTracker* memory_tracker_ = nullptr; }; #ifndef SWIG // Specifies that the output boundary edges should be sent to a single // S2Builder layer. This version can be used when the dimension of the // output geometry is known (e.g., intersecting two polygons to yield a // third polygon). S2BooleanOperation(OpType op_type, std::unique_ptr layer, const Options& options = Options()); // Specifies that the output boundary edges should be sent to three // different layers according to their dimension. Points (represented by // degenerate edges) are sent to layer 0, polyline edges are sent to // layer 1, and polygon edges are sent to layer 2. // // The dimension of an edge is defined as the minimum dimension of the two // input edges that produced it. For example, the intersection of two // crossing polyline edges is a considered to be a degenerate polyline // rather than a point, so it is sent to layer 1. Clients can easily // reclassify such polylines as points if desired, but this rule makes it // easier for clients that want to process point, polyline, and polygon // inputs differently. // // The layers are always built in the order 0, 1, 2, and all arguments to // the Build() calls are guaranteed to be valid until the last call returns. // All Graph objects have the same set of vertices and the same lexicon // objects, in order to make it easier to write classes that process all the // edges in parallel. S2BooleanOperation(OpType op_type, std::vector> layers, const Options& options = Options()); #endif OpType op_type() const { return op_type_; } const Options& options() const { return options_; } // Executes the given operation. Returns true on success, and otherwise // sets "error" appropriately. (This class does not generate any errors // itself, but the S2Builder::Layer might.) bool Build(const S2ShapeIndex& a, const S2ShapeIndex& b, S2Error* absl_nonnull error); // Convenience method that returns true if the result of the given operation // is empty. static bool IsEmpty(OpType op_type, const S2ShapeIndex& a, const S2ShapeIndex& b, const Options& options = Options()); // Convenience method that returns true if A intersects B. static bool Intersects(const S2ShapeIndex& a, const S2ShapeIndex& b, const Options& options = Options()) { return !IsEmpty(OpType::INTERSECTION, b, a, options); } // Convenience method that returns true if A contains B, i.e., if the // difference (B - A) is empty. static bool Contains(const S2ShapeIndex& a, const S2ShapeIndex& b, const Options& options = Options()) { return IsEmpty(OpType::DIFFERENCE, b, a, options); } // Convenience method that returns true if the symmetric difference of A and // B is empty. (Note that A and B may still not be identical, e.g. A may // contain two copies of a polyline while B contains one.) static bool Equals(const S2ShapeIndex& a, const S2ShapeIndex& b, const Options& options = Options()) { return IsEmpty(OpType::SYMMETRIC_DIFFERENCE, b, a, options); } private: class Impl; // The actual implementation. // Internal constructor to reduce code duplication. S2BooleanOperation(OpType op_type, const Options& options); // Specifies that "result_empty" should be set to indicate whether the exact // result of the operation is empty. This constructor is used to efficiently // test boolean relationships (see IsEmpty above). S2BooleanOperation(OpType op_type, bool* result_empty, const Options& options = Options()); Options options_; OpType op_type_; // The input regions. const S2ShapeIndex* regions_[2]; // The output consists either of zero layers, one layer, or three layers. std::vector> layers_; // The following field is set if and only if there are no output layers. bool* result_empty_ = nullptr; }; ////////////////// Implementation details follow //////////////////// inline S2BooleanOperation::SourceId::SourceId() : region_id_(0), shape_id_(0), edge_id_(-1) { } inline S2BooleanOperation::SourceId::SourceId(int region_id, int32_t shape_id, int32_t edge_id) : region_id_(region_id), shape_id_(shape_id), edge_id_(edge_id) {} inline S2BooleanOperation::SourceId::SourceId(int special_edge_id) : region_id_(0), shape_id_(0), edge_id_(special_edge_id) { } inline bool S2BooleanOperation::SourceId::operator==(SourceId other) const { return (region_id_ == other.region_id_ && shape_id_ == other.shape_id_ && edge_id_ == other.edge_id_); } inline bool S2BooleanOperation::SourceId::operator<(SourceId other) const { if (region_id_ < other.region_id_) return true; if (region_id_ > other.region_id_) return false; if (shape_id_ < other.shape_id_) return true; if (shape_id_ > other.shape_id_) return false; return edge_id_ < other.edge_id_; } #endif // S2_S2BOOLEAN_OPERATION_H_ src/s2/s2boolean_operation_test.cc000066400000000000000000003342311524103652300175120ustar00rootroot00000000000000// Copyright 2017 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s2boolean_operation.h" #include #include #include #include #include #include #include #include "absl/base/nullability.h" #include "absl/flags/declare.h" #include "absl/flags/flag.h" #include "absl/flags/reflection.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/log/log_streamer.h" #include "absl/random/bit_gen_ref.h" #include "absl/random/random.h" #include "absl/strings/match.h" #include "absl/strings/str_cat.h" #include "absl/strings/str_split.h" #include "absl/strings/string_view.h" #include "absl/types/span.h" #include "s2/mutable_s2shape_index.h" #include "s2/s1angle.h" #include "s2/s2builder.h" #include "s2/s2builder_graph.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_lax_polygon_layer.h" #include "s2/s2builderutil_s2point_vector_layer.h" #include "s2/s2builderutil_s2polyline_vector_layer.h" #include "s2/s2builderutil_snap_functions.h" #include "s2/s2builderutil_testing.h" #include "s2/s2edge_crossings.h" #include "s2/s2error.h" #include "s2/s2latlng.h" #include "s2/s2lax_polygon_shape.h" #include "s2/s2lax_polyline_shape.h" #include "s2/s2loop.h" #include "s2/s2memory_tracker.h" #include "s2/s2point.h" #include "s2/s2point_vector_shape.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2random.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2shapeutil_contains_brute_force.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" #include "s2/util/math/matrix3x3.h" ABSL_DECLARE_FLAG(int64_t, s2shape_index_tmp_memory_budget); namespace { using absl::ByAnyChar; using absl::SkipEmpty; using absl::StrCat; using absl::StrContains; using absl::string_view; using absl::StrSplit; using s2builderutil::IndexMatchingLayer; using s2builderutil::LaxPolygonLayer; using s2shapeutil::ContainsBruteForce; using std::make_unique; using std::pair; using std::string; using std::unique_ptr; using std::vector; using EdgeType = S2Builder::EdgeType; using Graph = S2Builder::Graph; using GraphOptions = S2Builder::GraphOptions; using DegenerateEdges = GraphOptions::DegenerateEdges; using DuplicateEdges = GraphOptions::DuplicateEdges; using SiblingPairs = GraphOptions::SiblingPairs; using OpType = S2BooleanOperation::OpType; using PolygonModel = S2BooleanOperation::PolygonModel; using PolylineModel = S2BooleanOperation::PolylineModel; using DegenerateBoundaries = LaxPolygonLayer::Options::DegenerateBoundaries; void ExpectResult(S2BooleanOperation::OpType op_type, const S2BooleanOperation::Options& options, const S2ShapeIndex& a, const S2ShapeIndex& b, const S2ShapeIndex& expected) { vector> layers; for (int dim = 0; dim < 3; ++dim) { // Since all S2Builder polygon layers require DISCARD or DISCARD_EXCESS // for degenerate edges, we intentionally do not require any specific // multiplicity for degenerate edges and sibling pairs of dimension 2. GraphOptions graph_options( EdgeType::DIRECTED, (dim == 2) ? DegenerateEdges::DISCARD_EXCESS : DegenerateEdges::KEEP, DuplicateEdges::KEEP, (dim == 2) ? SiblingPairs::DISCARD_EXCESS : SiblingPairs::KEEP); layers.push_back(make_unique( graph_options, &expected, dim)); } S2BooleanOperation op(op_type, std::move(layers), options); S2Error error; ASSERT_TRUE(op.Build(a, b, &error)) << S2BooleanOperation::OpTypeToString(op_type) << " failed:\n" << "Expected result: " << s2textformat::ToString(expected) << "\n" << error; // Now try the same thing with boolean output. EXPECT_EQ(expected.num_shape_ids() == 0, S2BooleanOperation::IsEmpty(op_type, a, b, options)); } void ExpectResult(S2BooleanOperation::OpType op_type, const S2BooleanOperation::Options& options, string_view a_str, string_view b_str, string_view expected_str) { auto a = s2textformat::MakeIndexOrDie(a_str); auto b = s2textformat::MakeIndexOrDie(b_str); auto expected = s2textformat::MakeIndexOrDie(expected_str); ExpectResult(op_type, options, *a, *b, *expected); } // The intersections in the "expected" data below were computed in lat-lng // space (i.e., the rectangular projection), while the actual intersections // are computed using geodesics. We can compensate for this by rounding the // intersection points to a fixed precision in degrees (e.g., 2 decimals). static S2BooleanOperation::Options RoundToE(int exp) { S2BooleanOperation::Options options; options.set_snap_function(s2builderutil::IntLatLngSnapFunction(exp)); return options; } TEST(S2BooleanOperation, OpTypeAccessor) { vector> layers; const S2BooleanOperation::Options options; S2BooleanOperation op(OpType::UNION, std::move(layers), options); EXPECT_EQ(OpType::UNION, op.op_type()); } // TODO(ericv): Clean up or remove these notes. // // Options to test: // polygon_model: OPEN, SEMI_OPEN, CLOSED // polyline_model: OPEN, SEMI_OPEN, CLOSED // polyline_loops_have_boundaries: true, false // conservative: true, false // // Geometry combinations to test: // // Point/point: // - disjoint, coincident // Point/polyline: // - Start vertex, end vertex, interior vertex, degenerate polyline // - With polyline_loops_have_boundaries: start/end vertex, degenerate polyline // Point/polygon: // - Polygon interior, exterior, vertex // - Vertex of degenerate sibling pair shell, hole // - Vertex of degenerate single point shell, hole // Polyline/polyline: // - Vertex intersection: // - Start, end, interior, degenerate, loop start/end, degenerate loop // - Test cases where vertex is not emitted because an incident edge is. // - Edge/edge: interior crossing, duplicate, reversed, degenerate // - Test that degenerate edges are ignored unless polyline has a single edge. // (For example, AA has one edge but AAA has no edges.) // Polyline/polygon: // - Vertex intersection: polyline vertex cases already covered, but test // polygon normal vertex, sibling pair shell/hole, single vertex shell/hole // - Also test cases where vertex is not emitted because an edge is. // - Edge/edge: interior crossing, duplicate, reversed // - Edge/interior: polyline edge in polygon interior, exterior // Polygon/polygon: // - Vertex intersection: // - normal vertex, sibling pair shell/hole, single vertex shell/hole // - Also test cases where vertex is not emitted because an edge is. // - Test that polygons take priority when there is a polygon vertex and // also isolated polyline vertices. (There should not be any points.) // - Edge/edge: interior crossing, duplicate, reversed // - Interior/interior: polygons in interior/exterior of other polygons TEST(S2BooleanOperation, DegeneratePolylines) { // Verify that degenerate polylines are preserved under all boundary models. S2BooleanOperation::Options options; auto a = "# 0:0, 0:0 #"; auto b = "# #"; options.set_polyline_model(PolylineModel::OPEN); ExpectResult(OpType::UNION, options, a, b, a); options.set_polyline_model(PolylineModel::SEMI_OPEN); ExpectResult(OpType::UNION, options, a, b, a); options.set_polyline_model(PolylineModel::CLOSED); ExpectResult(OpType::UNION, options, a, b, a); } TEST(S2BooleanOperation, DegeneratePolygons) { // Verify that degenerate polygon features (single-vertex and sibling pair // shells and holes) are preserved under all boundary models. S2BooleanOperation::Options options; auto a = "# # 0:0, 0:5, 5:5, 5:0; 1:1; 2:2, 3:3; 6:6; 7:7, 8:8"; auto b = "# #"; options.set_polygon_model(PolygonModel::OPEN); ExpectResult(OpType::UNION, options, a, b, a); options.set_polygon_model(PolygonModel::SEMI_OPEN); ExpectResult(OpType::UNION, options, a, b, a); options.set_polygon_model(PolygonModel::CLOSED); ExpectResult(OpType::UNION, options, a, b, a); } TEST(S2BooleanOperation, PointPoint) { S2BooleanOperation::Options options; auto a = "0:0 | 1:0 # #"; auto b = "0:0 | 2:0 # #"; // Note that these results have duplicates, which is correct. Clients can // eliminate the duplicates with the appropriate GraphOptions. ExpectResult(OpType::UNION, options, a, b, "0:0 | 0:0 | 1:0 | 2:0 # #"); ExpectResult(OpType::INTERSECTION, options, a, b, "0:0 | 0:0 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "1:0 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "1:0 | 2:0 # #"); } TEST(S2BooleanOperation, PointOpenPolyline) { // Tests operations between an open polyline and its vertices. // // The polyline "3:0, 3:0" consists of a single degenerate edge and contains // no points (since polyline_model() is OPEN). Since S2BooleanOperation // preserves degeneracies, this means that the union includes *both* the // point 3:0 and the degenerate polyline 3:0, since they do not intersect. // // This test uses Options::polyline_loops_have_boundaries() == true, which // means that the loop "4:0, 5:0, 4:0" does not contain the vertex "4:0". S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::OPEN); auto a = "0:0 | 1:0 | 2:0 | 3:0 | 4:0 | 5:0 # #"; auto b = "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"; ExpectResult(OpType::UNION, options, a, b, "0:0 | 2:0 | 3:0 | 4:0 " "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "1:0 | 5:0 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "0:0 | 2:0 | 3:0 | 4:0 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "0:0 | 2:0 | 3:0 | 4:0" "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); } TEST(S2BooleanOperation, PointOpenPolylineLoopBoundariesFalse) { // With Options::polyline_loops_have_boundaries() == false, the loop // "4:0, 5:0, 4:0" has two vertices, both of which are contained. S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::OPEN); options.set_polyline_loops_have_boundaries(false); auto a = "0:0 | 1:0 | 2:0 | 3:0 | 4:0 | 5:0 # #"; auto b = "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"; ExpectResult(OpType::UNION, options, a, b, "0:0 | 2:0 | 3:0 " "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "1:0 | 4:0 | 5:0 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "0:0 | 2:0 | 3:0 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "0:0 | 2:0 | 3:0 " "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); } TEST(S2BooleanOperation, PointSemiOpenPolyline) { // Degenerate polylines are defined not contain any points under the // SEMI_OPEN model either, so again the point 3:0 and the degenerate // polyline "3:0, 3:0" do not intersect. // // The result does not depend on Options::polyline_loops_have_boundaries(). S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::SEMI_OPEN); for (bool bool_value : {false, true}) { options.set_polyline_loops_have_boundaries(bool_value); auto a = "0:0 | 1:0 | 2:0 | 3:0 | 4:0 | 5:0 # #"; auto b = "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"; ExpectResult(OpType::UNION, options, a, b, "2:0 | 3:0 # 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "0:0 | 1:0 | 4:0 | 5:0 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "2:0 | 3:0 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "2:0 | 3:0 # 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); } } TEST(S2BooleanOperation, PointClosedPolyline) { // Under the CLOSED model, the degenerate polyline 3:0 does contain its // vertex. Since polylines take precedence over points, the union of the // point 3:0 and the polyline 3:0 is the polyline only. Similarly, since // subtracting a point from a polyline has no effect, the symmetric // difference includes only the polyline objects. // // The result does not depend on Options::polyline_loops_have_boundaries(). S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::CLOSED); for (bool bool_value : {false, true}) { options.set_polyline_loops_have_boundaries(bool_value); auto a = "0:0 | 1:0 | 2:0 | 3:0 | 4:0 | 5:0 # #"; auto b = "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "0:0 | 1:0 | 2:0 | 3:0 | 4:0 | 5:0 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0, 4:0 #"); } } TEST(S2BooleanOperation, PointPolygonInterior) { S2BooleanOperation::Options options; // PolygonModel is irrelevant. // One interior point and one exterior point. auto a = "1:1 | 4:4 # #"; auto b = "# # 0:0, 0:3, 3:0"; ExpectResult(OpType::UNION, options, a, b, "4:4 # # 0:0, 0:3, 3:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "1:1 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "4:4 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "4:4 # # 0:0, 0:3, 3:0"); } TEST(S2BooleanOperation, PointOpenPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::OPEN); // See notes about the two vertices below. auto a = "0:1 | 1:0 # #"; auto b = "# # 0:0, 0:1, 1:0"; ExpectResult(OpType::UNION, options, a, b, "0:1 | 1:0 # # 0:0, 0:1, 1:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "# #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "0:1 | 1:0 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "0:1 | 1:0 # # 0:0, 0:1, 1:0"); } TEST(S2BooleanOperation, PointSemiOpenPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::SEMI_OPEN); // The two vertices are chosen such that the polygon contains one vertex but // not the other under PolygonModel::SEMI_OPEN. (The same vertices are used // for all three PolygonModel options.) auto polygon = s2textformat::MakePolygonOrDie("0:0, 0:1, 1:0"); ASSERT_TRUE(polygon->Contains(s2textformat::MakePointOrDie("0:1"))); ASSERT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("1:0"))); auto a = "0:1 | 1:0 # #"; auto b = "# # 0:0, 0:1, 1:0"; ExpectResult(OpType::UNION, options, a, b, "1:0 # # 0:0, 0:1, 1:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "0:1 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "1:0 # #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "1:0 # # 0:0, 0:1, 1:0"); } TEST(S2BooleanOperation, PointClosedPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::CLOSED); // See notes about the two vertices above. auto a = "0:1 | 1:0 # #"; auto b = "# # 0:0, 0:1, 1:0"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:1, 1:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "0:1 | 1:0 # #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:1, 1:0"); } TEST(S2BooleanOperation, PolylineVertexOpenPolylineVertex) { // Test first, last, and middle vertices of both polylines. Also test // first/last and middle vertices of two polyline loops. // // Degenerate polylines are tested in PolylineEdgePolylineEdgeOverlap below. S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::OPEN); auto a = "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"; auto b = "# 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); // The output consists of the portion of each input polyline that intersects // the opposite region, so the intersection vertex is present twice. This // allows reassembling the individual polylins that intersect, if desired. // (Otherwise duplicates can be removed using DuplicateEdges::MERGE.) ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:1, 0:1 | 0:1, 0:1 #"); // Note that all operations are defined such that subtracting a // lower-dimensional subset of an object has no effect. In this case, // subtracting the middle vertex of a polyline has no effect. ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); } TEST(S2BooleanOperation, PolylineVertexOpenPolylineVertexLoopBoundariesFalse) { // With Options::polyline_loops_have_boundaries() == false, the 3 polyline // loops each have two vertices, both of which are contained. S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::OPEN); options.set_polyline_loops_have_boundaries(false); auto a = "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"; auto b = "# 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); // Note that the polyline "0:3, 0:4, 0:3" only has two vertices, not three. // This means that 0:3 is emitted only once for that polyline, plus once for // the other polyline, for a total of twice. ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:1, 0:1 | 0:1, 0:1 " "| 0:3, 0:3 | 0:3, 0:3 | 0:4, 0:4 | 0:4, 0:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); } TEST(S2BooleanOperation, PolylineVertexSemiOpenPolylineVertex) { // The result does not depend on Options::polyline_loops_have_boundaries(). S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::SEMI_OPEN); for (bool bool_value : {false, true}) { options.set_polyline_loops_have_boundaries(bool_value); auto a = "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"; auto b = "# 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:0 | 0:0, 0:0 | 0:1, 0:1 | 0:1, 0:1 " "| 0:3, 0:3 | 0:3, 0:3 | 0:4, 0:4 | 0:4, 0:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); } } TEST(S2BooleanOperation, PolylineVertexClosedPolylineVertex) { S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::CLOSED); auto a = "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"; auto b = "# 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); // Since Options::polyline_loops_have_boundaries() == true, the polyline // "0:3, 0:4, 0:3" has three vertices. Therefore 0:3 is emitted twice for // that polyline, plus once for the other polyline, for a total of thrice. ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:0 | 0:0, 0:0 | 0:1, 0:1 | 0:1, 0:1 " "| 0:2, 0:2 | 0:2, 0:2 " "| 0:3, 0:3 | 0:3, 0:3 | 0:3, 0:3 " "| 0:4, 0:4 | 0:4, 0:4 | 0:4, 0:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); } TEST(S2BooleanOperation, PolylineVertexClosedPolylineVertexLoopBoundariesFalse) { S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::CLOSED); options.set_polyline_loops_have_boundaries(false); auto a = "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"; auto b = "# 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); // Since Options::polyline_loops_have_boundaries() == false, the polyline // "0:3, 0:4, 0:3" has two vertices. Therefore 0:3 is emitted once for // that polyline, plus once for the other polyline, for a total of twice. ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:0 | 0:0, 0:0 | 0:1, 0:1 | 0:1, 0:1 " "| 0:2, 0:2 | 0:2, 0:2 " "| 0:3, 0:3 | 0:3, 0:3 | 0:4, 0:4 | 0:4, 0:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:3, 0:4, 0:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 0:1, 0:2 | 0:0, 1:0 | -1:1, 0:1, 1:1 | -1:2, 0:2 " "| 0:3, 0:4, 0:3 | 1:3, 0:3, 1:3 | 0:4, 1:4, 0:4 #"); } // The polygon used in the polyline/polygon vertex tests below. static string kVertexTestPolygonStr() { return "0:0, 0:1, 0:2, 0:3, 0:4, 0:5, 5:5, 5:4, 5:3, 5:2, 5:1, 5:0"; } TEST(S2BooleanOperation, TestSemiOpenPolygonVerticesContained) { // Verify whether certain vertices of the test polygon are contained under // the semi-open boundary model (for use in the tests below). auto polygon = s2textformat::MakePolygonOrDie(kVertexTestPolygonStr()); EXPECT_TRUE(polygon->Contains(s2textformat::MakePointOrDie("0:1"))); EXPECT_TRUE(polygon->Contains(s2textformat::MakePointOrDie("0:2"))); EXPECT_TRUE(polygon->Contains(s2textformat::MakePointOrDie("0:3"))); EXPECT_TRUE(polygon->Contains(s2textformat::MakePointOrDie("0:4"))); EXPECT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("5:1"))); EXPECT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("5:2"))); EXPECT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("5:3"))); EXPECT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("5:4"))); } // Don't bother testing every PolylineModel with every PolygonModel for vertex // intersection, since we have already tested the PolylineModels individually // above. It is sufficient to use PolylineModel::CLOSED with the various // PolygonModel options. TEST(S2BooleanOperation, PolylineVertexOpenPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::OPEN); // Define some constants to reduce code duplication. // Test all combinations of polylines that start or end on a polygon vertex, // where the polygon vertex is open or closed using semi-open boundaries, // and where the incident edge is inside or outside the polygon. auto a = ("# 1:1, 0:1 | 0:2, 1:2 | -1:3, 0:3 | 0:4, -1:4 " "| 6:1, 5:1 | 5:2, 6:2 | 4:3, 5:3 | 5:4, 4:4 #"); auto b = "# # " + kVertexTestPolygonStr(); const string kDifferenceResult = "# 0:1, 0:1 | 0:2, 0:2 | -1:3, 0:3 | 0:4, -1:4" "| 6:1, 5:1 | 5:2, 6:2 | 5:3, 5:3 | 5:4, 5:4 #"; ExpectResult(OpType::UNION, options, a, b, kDifferenceResult + kVertexTestPolygonStr()); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 0:1 | 0:2, 1:2 | 4:3, 5:3 | 5:4, 4:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, kDifferenceResult); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, kDifferenceResult + kVertexTestPolygonStr()); } // Like the test above, except that every polygon vertex is also incident to a // closed polyline vertex. This tests that when an open vertex and a closed // vertex coincide with each other, the result is considered closed. TEST(S2BooleanOperation, PolylineVertexOpenPolygonClosedPolylineVertex) { const string kTestGeometrySuffix = "-2:0, 0:1 | -2:1, 0:2 | -2:2, 0:3 | -2:3, 0:4 | " "7:0, 5:1 | 7:1, 5:2 | 7:2, 5:3 | 7:3, 5:4 # " + kVertexTestPolygonStr(); S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::OPEN); auto a = ("# 1:1, 0:1 | 0:2, 1:2 | -1:3, 0:3 | 0:4, -1:4 " "| 6:1, 5:1 | 5:2, 6:2 | 4:3, 5:3 | 5:4, 4:4 #"); auto b = ("# " + kTestGeometrySuffix); const string kDifferencePrefix = "# -1:3, 0:3 | 0:4, -1:4 | 6:1, 5:1 | 5:2, 6:2"; ExpectResult(OpType::UNION, options, a, b, kDifferencePrefix + " | 0:1, 0:1 | 0:2, 0:2 | 5:3, 5:3 | 5:4, 5:4 | " + kTestGeometrySuffix); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 0:1 | 0:2, 1:2 | 0:3, 0:3 | 0:4, 0:4" "| 5:1, 5:1 | 5:2, 5:2 | 4:3, 5:3 | 5:4, 4:4" "| 0:1, 0:1 | 0:2, 0:2 | 0:3, 0:3 | 0:4, 0:4" "| 5:1, 5:1 | 5:2, 5:2 | 5:3, 5:3 | 5:4, 5:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, kDifferencePrefix + " #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, kDifferencePrefix + " | " + kTestGeometrySuffix); } TEST(S2BooleanOperation, PolylineVertexSemiOpenPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::SEMI_OPEN); // Test all combinations of polylines that start or end on a polygon vertex, // where the polygon vertex is open or closed using semi-open boundaries, // and where the incident edge is inside or outside the polygon. // // The vertices at latitude 0 used below are all closed while the vertices // at latitude 5 are all open (see TestSemiOpenPolygonVerticesContained). auto a = ("# 1:1, 0:1 | 0:2, 1:2 | -1:3, 0:3 | 0:4, -1:4 " "| 6:1, 5:1 | 5:2, 6:2 | 4:3, 5:3 | 5:4, 4:4 #"); auto b = "# # " + kVertexTestPolygonStr(); const string kDifferenceResult = "# -1:3, 0:3 | 0:4, -1:4 | 6:1, 5:1 | 5:2, 6:2 | 5:3, 5:3 | 5:4, 5:4 #"; ExpectResult(OpType::UNION, options, a, b, kDifferenceResult + kVertexTestPolygonStr()); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 0:1 | 0:2, 1:2 | 0:3, 0:3 | 0:4, 0:4 " "| 4:3, 5:3 | 5:4, 4:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, kDifferenceResult); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, kDifferenceResult + kVertexTestPolygonStr()); } TEST(S2BooleanOperation, PolylineVertexClosedPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::CLOSED); // Test all combinations of polylines that start or end on a polygon vertex, // where the polygon vertex is open or closed using semi-open boundaries, // and where the incident edge is inside or outside the polygon. auto a = ("# 1:1, 0:1 | 0:2, 1:2 | -1:3, 0:3 | 0:4, -1:4 " "| 6:1, 5:1 | 5:2, 6:2 | 4:3, 5:3 | 5:4, 4:4 #"); auto b = "# # " + kVertexTestPolygonStr(); const string kDifferenceResult = "# -1:3, 0:3 | 0:4, -1:4 | 6:1, 5:1 | 5:2, 6:2 #"; ExpectResult(OpType::UNION, options, a, b, kDifferenceResult + kVertexTestPolygonStr()); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 0:1 | 0:2, 1:2 | 0:3, 0:3 | 0:4, 0:4" "| 5:1, 5:1 | 5:2, 5:2 | 4:3, 5:3 | 5:4, 4:4 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, kDifferenceResult); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, kDifferenceResult + kVertexTestPolygonStr()); } TEST(S2BooleanOperation, PolylineEdgePolylineEdgeCrossing) { // Two polyline edges that cross at a point interior to both edges. S2BooleanOperation::Options options = RoundToE(1); auto a = "# 0:0, 2:2 #"; auto b = "# 2:0, 0:2 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 1:1, 2:2 | 2:0, 1:1, 0:2 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 1:1 | 1:1, 1:1 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 1:1, 2:2 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:0, 1:1, 2:2 | 2:0, 1:1, 0:2 #"); } TEST(S2BooleanOperation, PolylineEdgePolylineEdgeOverlap) { // The PolylineModel does not affect this calculation. In particular the // intersection of a degenerate polyline edge with itself is non-empty, even // though the edge contains no points in the OPEN and SEMI_OPEN models. S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::OPEN); // Test edges in the same and reverse directions, and degenerate edges. auto a = "# 0:0, 1:0, 2:0, 2:5 | 3:0, 3:0 | 6:0, 5:0, 4:0 #"; auto b = "# 0:0, 1:0, 2:0 | 3:0, 3:0 | 4:0, 5:0 #"; // As usual, the expected output includes the relevant portions of *both* // input polylines. Duplicates can be removed using GraphOptions. ExpectResult(OpType::UNION, options, a, b, "# 0:0, 1:0, 2:0, 2:5 | 0:0, 1:0, 2:0 | 3:0, 3:0 | 3:0, 3:0 " "| 6:0, 5:0, 4:0 | 4:0, 5:0 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 1:0, 2:0 | 0:0, 1:0, 2:0 | 3:0, 3:0 | 3:0, 3:0 " "| 5:0, 4:0 | 4:0, 5:0 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 2:0, 2:5 | 6:0, 5:0 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 2:0, 2:5 | 6:0, 5:0 #"); } TEST(S2BooleanOperation, PolylineLoopMultipleOpenPolylineEdge) { // Here we test a polyline loop ABCA with the pairs {AA, AB} and {AA, AC}. // This tests not only what happens when degenerate polylines intersect loop // endpoints, but also what happens when polylines intersect a degenerate // and non-degenerate edge that overlap each other. S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::OPEN); auto a = "# 0:0, 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2, 2:2 #"; auto b = "# 0:0, 0:0 | 0:0, 0:1 | 2:2, 2:2 | 2:2, 3:2 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 1:0, 0:0 | 0:0, 0:0 | 0:0, 0:1 " "| 2:2, 2:3, 3:2, 2:2 | 2:2, 2:2 | 2:2, 3:2 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:1 | 0:0, 0:1 | 2:2, 3:2 | 3:2, 2:2 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 0:0, 0:0 | 2:2, 2:3, 3:2 | 2:2, 2:2 #"); } TEST(S2BooleanOperation, PolylineLoopMultipleSemiOpenPolylineEdge) { // Like the test above but with SEMI_OPEN boundaries. In this case ABCA // intersected with {AA, AB} is {AA, AB, AB} but ABCA intersected with {AA, // AC} is {AA, AA, AC, CA} since the chain ABCA contains its start vertex // but not its end vertex. S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::SEMI_OPEN); auto a = "# 0:0, 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2, 2:2 #"; auto b = "# 0:0, 0:0 | 0:0, 0:1 | 2:2, 2:2 | 2:2, 3:2 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 1:0, 0:0 | 0:0, 0:0 | 0:0, 0:1 " "| 2:2, 2:3, 3:2, 2:2 | 2:2, 2:2 | 2:2, 3:2 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:0 | 0:0, 0:1 | 0:0, 0:1 " "| 2:2, 2:2 | 2:2, 2:2 | 2:2, 3:2 | 3:2, 2:2 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); } TEST(S2BooleanOperation, PolylineLoopMultipleClosedPolylineEdge) { // Like the test above but with CLOSED boundaries. In this case ABCA // intersected with {AA, AB} is {AA, AA, AB, AB} since the chain ABCA // contains both its start vertex and end vertex. S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::CLOSED); auto a = "# 0:0, 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2, 2:2 #"; auto b = "# 0:0, 0:0 | 0:0, 0:1 | 2:2, 2:2 | 2:2, 3:2 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 1:0, 0:0 | 0:0, 0:0 | 0:0, 0:1 " "| 2:2, 2:3, 3:2, 2:2 | 2:2, 2:2 | 2:2, 3:2 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:0 | 0:0, 0:0 | 0:0, 0:1 | 0:0, 0:1 " "| 2:2, 2:2 | 2:2, 2:2 | 2:2, 3:2 | 3:2, 2:2 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); } TEST(S2BooleanOperation, PolylineLoopMultiplePolylineEdgeLoopBoundariesFalse) { // Like the tests above but with polyline_loops_have_boundaries() == false. // In this case the result does not depend on the polyline model. The // polyline AA intersects ABCA exactly once, and the intersection of ABCA // with {AA, AB} is {AA, AB, AB}. for (auto polyline_model : { PolylineModel::OPEN, PolylineModel::SEMI_OPEN, PolylineModel::CLOSED}) { S2BooleanOperation::Options options; options.set_polyline_model(polyline_model); options.set_polyline_loops_have_boundaries(false); auto a = "# 0:0, 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2, 2:2 #"; auto b = "# 0:0, 0:0 | 0:0, 0:1 | 2:2, 2:2 | 2:2, 3:2 #"; ExpectResult(OpType::UNION, options, a, b, "# 0:0, 0:1, 1:0, 0:0 | 0:0, 0:0 | 0:0, 0:1 " "| 2:2, 2:3, 3:2, 2:2 | 2:2, 2:2 | 2:2, 3:2 #"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 0:0, 0:0 | 0:0, 0:1 | 0:0, 0:1 " "| 2:2, 2:2 | 2:2, 3:2 | 3:2, 2:2 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 0:1, 1:0, 0:0 | 2:2, 2:3, 3:2 #"); } } TEST(S2BooleanOperation, PolylineEdgeOpenPolygonEdgeOverlap) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::OPEN); // A polygon and two polyline edges that coincide with the polygon boundary, // one in the same direction and one in the reverse direction. auto a = "# 1:1, 1:3, 3:3 | 3:3, 1:3 # "; auto b = "# # 1:1, 1:3, 3:3, 3:1"; ExpectResult(OpType::UNION, options, a, b, "# 1:1, 1:3, 3:3 | 3:3, 1:3 # 1:1, 1:3, 3:3, 3:1"); ExpectResult(OpType::INTERSECTION, options, a, b, "# #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 1:1, 1:3, 3:3 | 3:3, 1:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 1:1, 1:3, 3:3 | 3:3, 1:3 # 1:1, 1:3, 3:3, 3:1"); } TEST(S2BooleanOperation, PolylineEdgeSemiOpenPolygonEdgeOverlap) { auto polygon = s2textformat::MakePolygonOrDie("1:1, 1:3, 3:3, 3:1"); ASSERT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("1:1"))); ASSERT_TRUE(polygon->Contains(s2textformat::MakePointOrDie("1:3"))); ASSERT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("3:3"))); ASSERT_FALSE(polygon->Contains(s2textformat::MakePointOrDie("3:1"))); S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::SEMI_OPEN); auto a = "# 1:1, 1:3, 3:3 | 3:3, 1:3 # "; auto b = "# # 1:1, 1:3, 3:3, 3:1"; ExpectResult(OpType::UNION, options, a, b, "# 1:1, 1:1 | 3:3, 3:3 | 3:3, 1:3 # 1:1, 1:3, 3:3, 3:1"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:3, 1:3 | 1:1, 1:3, 3:3 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 1:1, 1:1 | 3:3, 3:3 | 3:3, 1:3 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 1:1, 1:1 | 3:3, 3:3 | 3:3, 1:3 # 1:1, 1:3, 3:3, 3:1"); } TEST(S2BooleanOperation, PolylineEdgeClosedPolygonEdgeOverlap) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::CLOSED); auto a = "# 1:1, 1:3, 3:3 | 3:3, 1:3 # "; auto b = "# # 1:1, 1:3, 3:3, 3:1"; ExpectResult(OpType::UNION, options, a, b, "# # 1:1, 1:3, 3:3, 3:1"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 1:3, 3:3 | 3:3, 1:3 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 1:1, 1:3, 3:3, 3:1"); } TEST(S2BooleanOperation, PolygonVertexMatching) { // This test shows that CrossingProcessor::ProcessEdgeCrossings() must set // a0_matches_polygon and a1_matches_polygon correctly even when (a0, a1) // itself is a polygon edge (or its sibling). (It requires degenerate // polygon geometry to demonstrate this.) S2BooleanOperation::Options options; options.set_polyline_model(PolylineModel::CLOSED); options.set_polygon_model(PolygonModel::CLOSED); auto a = "# 0:0, 1:1 # "; auto b = "# # 0:0, 1:1"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 1:1"); } TEST(S2BooleanOperation, PolylineEdgePolygonInterior) { S2BooleanOperation::Options options; // PolygonModel is irrelevant. // One normal and one degenerate polyline edge in the polygon interior, and // similarly for the polygon exterior. auto a = "# 1:1, 2:2 | 3:3, 3:3 | 6:6, 7:7 | 8:8, 8:8 # "; auto b = "# # 0:0, 0:5, 5:5, 5:0"; ExpectResult(OpType::UNION, options, a, b, "# 6:6, 7:7 | 8:8, 8:8 # 0:0, 0:5, 5:5, 5:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "# 1:1, 2:2 | 3:3, 3:3 #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# 6:6, 7:7 | 8:8, 8:8 #"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# 6:6, 7:7 | 8:8, 8:8 # 0:0, 0:5, 5:5, 5:0"); } TEST(S2BooleanOperation, PolylineEdgeIsolatedStartVertexPlusInteriorCrossing) { // Tests a polyline XYZ that when intersected with a polygon results in an // isolated vertex X plus a clipped portion UYV. This case is unusual // because the isolated vertex is handled by creating a separate degenerate // S2Builder input edge XX which is added before the actual edge XY, and the // crossing edge information needs to be associated with XY rather than XX // in order for GraphEdgeClipper to be able to do its work properly. The // test is constructed such that if the crossings are incorrectly associated // with the degenerate edge XX then not only will the output be incorrect, // it will also trigger an internal ABSL_DCHECK. S2BooleanOperation::Options options = RoundToE(1); auto a = "# 0:0, 0:10, 0:4 # "; auto b = "# # 0:0, -5:5, 5:5"; ExpectResult(OpType::DIFFERENCE, options, a, b, "# 0:0, 0:0 | 0:5, 0:10, 0:5 #"); } TEST(S2BooleanOperation, PolygonEdgeIsolatedStartVertexPlusInteriorCrossing) { // Similar to the case above, but tests a polygon XYZ rather than a // polyline. This requires using the CLOSED polygon model and computing the // intersection with a clockwise loop rather than subtracting a CCW loop. // The test is constructed such that if the crossings for the edge 0:0, 0:8 // are incorrectly associated with the degenerate edge 0:0, then not only // will the output be incorrect, it will also trigger an internal ABSL_DCHECK. S2BooleanOperation::Options options = RoundToE(1); options.set_polygon_model(PolygonModel::CLOSED); auto a = "# # 0:0, 5:5, -5:5"; auto b = "# # 1:4, 0:0, 0:8"; ExpectResult(OpType::INTERSECTION, options, a, b, "# # 0:0; 0:5, 0:8, 0.8:5"); } TEST(S2BooleanOperation, PolygonVertexOpenPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::OPEN); auto a = "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5"; auto b = "# # 0:0, 5:3, 5:2"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5, 0:0, 5:3, 5:2"); ExpectResult(OpType::INTERSECTION, options, a, b, "# #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5, 0:0, 5:3, 5:2"); } TEST(S2BooleanOperation, PolygonVertexSemiOpenPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::SEMI_OPEN); auto a = "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5"; auto b = "# # 0:0, 5:3, 5:2"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5, 0:0, 5:3, 5:2"); ExpectResult(OpType::INTERSECTION, options, a, b, "# #"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5, 0:0, 5:3, 5:2"); } TEST(S2BooleanOperation, PolygonVertexClosedPolygonVertex) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::CLOSED); auto a = "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5"; auto b = "# # 0:0, 5:3, 5:2"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5, 0:0, 5:3, 5:2"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 0:0"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5"); ExpectResult(OpType::DIFFERENCE, options, b, a, "# # 0:0, 5:3, 5:2"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:5, 1:5, 0:0, 2:5, 3:5, 0:0, 5:3, 5:2"); } TEST(S2BooleanOperation, PolygonEdgePolygonEdgeCrossing) { // Two polygons whose edges cross at points interior to both edges. S2BooleanOperation::Options options = RoundToE(2); auto a = "# # 0:0, 0:2, 2:2, 2:0"; auto b = "# # 1:1, 1:3, 3:3, 3:1"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:2, 1:2, 1:3, 3:3, 3:1, 2:1, 2:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 1:1, 1:2, 2:2, 2:1"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:2, 1:2, 1:1, 2:1, 2:0"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:2, 1:2, 1:1, 2:1, 2:0; " "1:2, 1:3, 3:3, 3:1, 2:1, 2:2"); } TEST(S2BooleanOperation, PolygonEdgeOpenPolygonEdgeOverlap) { S2BooleanOperation::Options options; // One shape is a rectangle, the other consists of one triangle inside the // rectangle and one triangle outside the rectangle, where each triangle // shares one edge with the rectangle. This implies that the edges are in // the same direction in one case and opposite directions in the other case. options.set_polygon_model(PolygonModel::OPEN); auto a = "# # 0:0, 0:4, 2:4, 2:0"; auto b = "# # 0:0, 1:1, 2:0; 0:4, 1:5, 2:4"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:4, 2:4, 2:0; 0:4, 1:5, 2:4"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 0:0, 1:1, 2:0"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:4, 2:4, 2:0, 1:1"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:4, 2:4, 2:0, 1:1; 0:4, 1:5, 2:4"); } TEST(S2BooleanOperation, PolygonEdgeSemiOpenPolygonEdgeOverlap) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::SEMI_OPEN); auto a = "# # 0:0, 0:4, 2:4, 2:0"; auto b = "# # 0:0, 1:1, 2:0; 0:4, 1:5, 2:4"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:4, 1:5, 2:4, 2:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 0:0, 1:1, 2:0"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:4, 2:4, 2:0, 1:1"); // Note that SYMMETRIC_DIFFERENCE does not guarantee that results are // normalized, i.e. the output could contain siblings pairs (which can be // discarded using S2Builder::GraphOptions). ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:4, 2:4, 2:0, 1:1; 0:4, 1:5, 2:4"); } TEST(S2BooleanOperation, PolygonEdgeClosedPolygonEdgeOverlap) { S2BooleanOperation::Options options; options.set_polygon_model(PolygonModel::CLOSED); auto a = "# # 0:0, 0:4, 2:4, 2:0"; auto b = "# # 0:0, 1:1, 2:0; 0:4, 1:5, 2:4"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:4, 1:5, 2:4, 2:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 0:0, 1:1, 2:0; 0:4, 2:4"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:4, 2:4, 2:0, 1:1"); // Note that SYMMETRIC_DIFFERENCE does not guarantee that results are // normalized, i.e. the output could contain siblings pairs. ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:4, 2:4, 2:0, 1:1; 0:4, 1:5, 2:4"); } TEST(S2BooleanOperation, PolygonPolygonInterior) { S2BooleanOperation::Options options; // PolygonModel is irrelevant. // One loop in the interior of another polygon and one loop in the exterior. auto a = "# # 0:0, 0:4, 4:4, 4:0"; auto b = "# # 1:1, 1:2, 2:2, 2:1; 5:5, 5:6, 6:6, 6:5"; ExpectResult(OpType::UNION, options, a, b, "# # 0:0, 0:4, 4:4, 4:0; 5:5, 5:6, 6:6, 6:5"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 1:1, 1:2, 2:2, 2:1"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:0, 0:4, 4:4, 4:0; 2:1, 2:2, 1:2, 1:1"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:0, 0:4, 4:4, 4:0; 2:1, 2:2, 1:2, 1:1; " "5:5, 5:6, 6:6, 6:5"); } TEST(S2BooleanOperation, PolygonEdgesDegenerateAfterSnapping) { S2BooleanOperation::Options options = RoundToE(0); // Two narrow rectangles forming a plus sign. auto a = "# # 0:-1, 0:1, 0.1:1, 0.1:-1"; auto b = "# # -1:0.1, 1:0.1, 1:0, -1:0"; // When snapping causes an output edge to become degenerate, it is still // emitted (since otherwise loops that contract to a single point would be // lost). If the output layer doesn't want such edges, they can be removed // via DegenerateEdges::DISCARD. ExpectResult(OpType::UNION, options, a, b, "# # 0:-1, 0:0, 0:1, 0:0 | " "-1:0, 0:0, 1:0, 0:0"); ExpectResult(OpType::INTERSECTION, options, a, b, "# # 0:0"); ExpectResult(OpType::DIFFERENCE, options, a, b, "# # 0:-1, 0:0, 0:1, 0:0"); ExpectResult(OpType::SYMMETRIC_DIFFERENCE, options, a, b, "# # 0:-1, 0:0, 0:1, 0:0 | " "-1:0, 0:0, 1:0, 0:0"); } // The following class comprehensively tests the handling of degenerate // geometry. It is used to implement over 4,000 individual test cases encoded // as a series of textual tables. class DegeneracyCoverageTest : public ::testing::Test { public: // Verifies that the S2BooleanOperation results for the given OpType and // PolygonModel match the given set of rules (encoded as described below). void Run(OpType op_type, PolygonModel polygon_model, absl::Span rules); private: // The inputs to the test cases are intended to span all possible types of // degenerate and non-degenerate edge configurations in the vicinity of an // individual input edge. Essentially we are trying to cover all possible // behaviors of S2BooleanOperation::Impl::CrossingProcessor::ProcessEdge(), // which is responsible for determining which parts of each input edge // should be emitted to the output. // // For this purpose it is sufficient to consider two points A and B and the // possible types of degeneracies that involve just these two points. The // actual locations of the points are immaterial, although for descriptive // purposes we suppose that B is located above A so that the edge AB is // considered "up" while the edge BA is considered "down". Only one point // needs to be considered for point degeneracies, so we use A for this // purpose. This means that all inputs consist of some subset of AA, AB, // and BA represented as edges of dimensions 0, 1, or 2. For example, a // polyline edge intersected with a point located at one of its vertices // would be represented as the edge AB of dimension 1 in region 0 and the // edge AA of dimension 0 in region 1. // // Each possibility is represented as a single letter as follows (with the // corresponding edges in braces): // // Special: . = empty {} // * = full sphere {} // // Dimension 0: p = point {AA} // // Dimension 1: P = point polyline {AA} // u = up edge {AB} // d = down edge {BA} // // Dimension 2: s = point shell {AA} // S = sibling pair shell {AB, BA} // U = up edge {AB} // D = down edge {BA} // H = sibling pair hole {AB, BA} // h = point hole {AA} // // Using this encoding, the test case described above would be represented // as 'u' for region 0 and 'p' for region 1. Note that while the test cases // focus only on what happens to the edges AB, BA, and AA, additional edges // are needed in order to construct valid inputs. For example, the test // case U (the "up" polygon edge AB) is represented as a triangle ABC, while // the test case D (the "down" polygon edge BA) is represented as the // triangle AB(-C). // // The expected result of a given operation is then represented as a // sequence of the characters above. In some cases additional symbols are // needed to define the expected results. For example, in the closed // polygon model the union of U and D is the quadrilateral A(-C)BC which // does not appear in the list of symbols above. So the results use the // following additional symbols: // // Q : the union of the "U" and "D" shapes (a quadrilateral) // B : a point polyline consisting only of the vertex B {BB} // // Finally, in some cases the expected result depends on the polyline model, // or on whether one of the two regions contains the vertex A. For example, // the intersection of 'p' and 'U' in the semi-open model depends on whether // the representation of U (the triangle ABC mentioned above) contains its // vertex A. Conditional results of this sort are encoded using the // following operators: // // ~X : the complement of X (where X must be either U or D) // XY : the result is X if region 1 contains point A, otherwise Y. // X|Y|Z : the result is X, Y, or Z depending on whether the polyline // model is OPEN, SEMI_OPEN, or CLOSED. // // The operators above may be combined, e.g. X<>Y means the result is X if // both regions contain point A and Y otherwise. // These are the characters representing possible input regions, in the // order they are used in the rules listed further below. const string kInputChars = ".pPudsSUDHh*"; // Returns an S2ShapeIndex corresponding to the given string of characters. unique_ptr MakeIndex(string_view chars) const; // Verifies that S2BooleanOperation returns the given result for the inputs // represented by the characters 'ch0' and 'ch1'. void TestResult(OpType op_type, const S2BooleanOperation::Options& options, char ch0, char ch1, string_view result) const; }; void DegeneracyCoverageTest::Run(OpType op_type, PolygonModel polygon_model, absl::Span rules) { ABSL_CHECK_EQ(rules.size(), kInputChars.size()); // For the symmetric operators (i.e., all except difference) we only need to // define half of the expected results. const bool symmetric = (op_type != OpType::DIFFERENCE); // Possible values for Options::polyline_model(). const vector kPolylineModels = { PolylineModel::OPEN, PolylineModel::SEMI_OPEN, PolylineModel::CLOSED }; // Possible values for Options::polyline_loops_have_boundaries(). const vector kPolylineLoopOptions = { true, false }; // The set of characters representing polyline inputs. const string kLineChars = "Pud"; // The following nested loops iterate over all combinations of: // - Input character 0 // - Input character 1 // - polyline model (if either input is a polyline) // - whether a closed polyline loop is considered to have a boundary // (if either input is a degenerate polyline) S2BooleanOperation::Options options; options.set_polygon_model(polygon_model); for (int i = 0; i < kInputChars.size(); ++i) { char ch0 = kInputChars[i]; vector row = StrSplit(rules[i], ' ', SkipEmpty()); // Verify and remove the row label. ABSL_CHECK_EQ(row[0], string{ch0}); ABSL_CHECK_EQ(row[1], "|"); row.erase(row.begin(), row.begin() + 2); const int limit = symmetric ? (i + 1) : kInputChars.size(); ABSL_CHECK_EQ(row.size(), limit); for (int j = 0; j < limit; ++j) { char ch1 = kInputChars[j]; // Only iterate over polyline models if at least one input is a polyline. int num_line_models = (StrContains(kLineChars, ch0) || StrContains(kLineChars, ch1)) ? 3 : 1; for (int k = 0; k < num_line_models; ++k) { options.set_polyline_model(kPolylineModels[k]); // Only iterate over polyline loop boundary options if at least one // input is a degenerate polyline. int num_polyline_loop_options = (ch0 == 'P' || ch1 == 'P') ? 2 : 1; for (int m = 0; m < num_polyline_loop_options; ++m) { options.set_polyline_loops_have_boundaries(kPolylineLoopOptions[m]); string_view code = row[j]; // Process any '<' or '>' operators in the result. vector choices = StrSplit(code, ByAnyChar("<>"), SkipEmpty()); string_view result = choices[0]; if (choices.size() > 1) { ABSL_CHECK_EQ(choices.size(), 2); // Test whether each input contains the point A. Note that we // can't use S2ContainsPointQuery because the containment test // must be done using the given S2BooleanOperation options. bool in0 = S2BooleanOperation::Contains(*MakeIndex(string{ch0}), *MakeIndex("p"), options); bool in1 = S2BooleanOperation::Contains(*MakeIndex(string{ch1}), *MakeIndex("p"), options); // If the point containment conditions specified by the operators // '<' and '>' are satisfied then the result is choices[0], // otherwise it is choices[1]. if ((StrContains(code, '<') && !in0) || (StrContains(code, '>') && !in1)) { result = choices[1]; } } // Next process any '|' operators in the result. choices = StrSplit(result, '|'); if (choices.size() > 1) { ABSL_CHECK_EQ(num_line_models, 3) << "No polylines present"; ABSL_CHECK_EQ(choices.size(), 3); result = choices[k]; } TestResult(op_type, options, ch0, ch1, result); if (symmetric && j != i) { TestResult(op_type, options, ch1, ch0, result); } } } } } } void DegeneracyCoverageTest::TestResult( OpType op_type, const S2BooleanOperation::Options& options, char ch0, char ch1, string_view result) const { auto index0 = MakeIndex(string{ch0}); auto index1 = MakeIndex(string{ch1}); auto expected = MakeIndex(result); SCOPED_TRACE(absl::StrCat( "\n Operation: ", S2BooleanOperation::OpTypeToString(op_type), "\n PolygonModel: ", S2BooleanOperation::PolygonModelToString(options.polygon_model()), "\n PolylineModel: ", S2BooleanOperation::PolylineModelToString(options.polyline_model()), "\n polyline_loops_have_boundaries: ", options.polyline_loops_have_boundaries() ? "true" : "false", "\n Inputs: ", string{ch0}, ", ", string{ch1}, "\n Expected: ", result)); ExpectResult(op_type, options, *index0, *index1, *expected); } unique_ptr DegeneracyCoverageTest::MakeIndex( string_view chars) const { // The locations of A, B, C are arbitrary, however some tests are sensitive // as to whether certain polygons contain the points {A, B} or not. If // these points are moved then some test results may need to be changed. S2Point a(1, 0, 0), b(0, 0, 1), c(0, 1, 0); auto index = make_unique(); for (int i = 0; i < chars.size(); ++i) { using Loops = vector>; char ch = chars[i]; if (ch == '.') { // Empty } else if (ch == 'p') { // Point index->Add(make_unique(vector{a})); } else if (ch == 'P') { // Polyline consisting only of the point A index->Add(make_unique(vector{a, a})); } else if (ch == 'B') { // Polyline consisting only of the point B index->Add(make_unique(vector{b, b})); } else if (ch == 'u') { // Upwards polyline edge index->Add(make_unique(vector{a, b})); } else if (ch == 'd') { // Downwards polyline edge index->Add(make_unique(vector{b, a})); } else if (ch == 's') { // Point shell index->Add(make_unique(Loops{{a}})); } else if (ch == 'S') { // Sibling pair shell index->Add(make_unique(Loops{{a, b}})); } else if (ch == 'U') { // Upwards polygon edge int i = index->Add(make_unique(Loops{{a, b, -c}})); // Some test results require that the U polygon contains A but not B. ABSL_CHECK(ContainsBruteForce(*index->shape(i), a)); ABSL_CHECK(!ContainsBruteForce(*index->shape(i), b)); } else if (ch == 'D') { // Downwards polygon edge int i = index->Add(make_unique(Loops{{b, a, c}})); // Some test cases require that the D polygon excludes both A and B. ABSL_CHECK(!ContainsBruteForce(*index->shape(i), a)); ABSL_CHECK(!ContainsBruteForce(*index->shape(i), b)); } else if (ch == '~') { // Complement of following region (U or D) ch = chars[++i]; if (ch == 'U') { index->Add(make_unique(Loops{{-c, b, a}})); } else if (ch == 'D') { index->Add(make_unique(Loops{{c, a, b}})); } else { ABSL_LOG(FATAL) << "Unsupported character for ~ operator: " << string{ch}; } } else if (ch == 'Q') { // Union of 'U' and 'D' shapes index->Add(make_unique(Loops{{a, c, b, -c}})); } else if (ch == 'H') { // Sibling pair hole index->Add(make_unique(Loops{{a, b}, {}})); } else if (ch == 'h') { // Point hole index->Add(make_unique(Loops{{a}, {}})); } else if (ch == '*') { // Full sphere index->Add(make_unique(Loops{{}})); } else { ABSL_LOG(FATAL) << "Unknown degeneracy coverage symbol: " << string{ch}; } } return index; } TEST_F(DegeneracyCoverageTest, OpenIntersection) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | . pp", "P | . p<. PP", "u | . p<. PP<. uu", "d | . p<. PP<. ud dd", "s | . . . . . s", "S | . . . . . . S", "U | . . . . . . . U", "D | . . . . . . . . D", "H | . . . . . . . U D H", "h | . . . u d . S U D H h", "* | . p P u d s S U D H h *", }; Run(OpType::INTERSECTION, PolygonModel::OPEN, rules); } TEST_F(DegeneracyCoverageTest, SemiOpenIntersection) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | . pp", "P | . p<. PP", "u | . p<. PP<. uu", "d | . p<. PP<. ud dd", "s | . . . . . s", "S | . p<. P<. . . s<. S", "U | . p<. P<. u P<>. s<. . U", "D | . p<. P<. P<>. d s<. . . D", "H | . p<. P<. u d s<. . U D H", "h | . p P u d . S U D H h", "* | . p P u d s S U D H h *", }; Run(OpType::INTERSECTION, PolygonModel::SEMI_OPEN, rules); } TEST_F(DegeneracyCoverageTest, ClosedIntersection) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | . pp", "P | . p<. PP", "u | . p<. PP<. uu", "d | . p<. PP<. ud dd", "s | . p P P>. P>. s", "S | . p P u d s S", "U | . p P u d s S U", "D | . p P u d s S S D", "H | . p P u d s S U D H", "h | . p P u d s S U D H h", "* | . p P u d s S U D H h *", }; Run(OpType::INTERSECTION, PolygonModel::CLOSED, rules); } TEST_F(DegeneracyCoverageTest, OpenUnion) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | p pp", "P | P Ph Ph>h h h h h h h", "* | * * * * * * * * * * * *", }; Run(OpType::UNION, PolygonModel::OPEN, rules); } TEST_F(DegeneracyCoverageTest, SemiOpenUnion) { // CAVEAT: The results for (U,u) and (D,d) require the U polygon to contain // vertex A but not vertex B, and the D polygon to contain neither vertex. // This differs from most of the other tests, which encode the results // conditionally using the '<' and '>' operators. That was not practical in // this case because (1) no conditional operators are defined for the 'B' // vertex and (2) encoding the full set of possibilities for all 12 cases // (i.e., the 3 polyline models and whether U contains A and/or B) would be // unwieldy. const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | p pp", "P | P Ph *>h *>h *>h h", "* | * * * * * * * * * * * *", }; Run(OpType::UNION, PolygonModel::SEMI_OPEN, rules); } TEST_F(DegeneracyCoverageTest, ClosedUnion) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | p pp", "P | P P rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | . . . . . . . . . . . .", "p | p . .>p .>p .>p p p p p p p .", "P | P P . .>P .>P P P P P P P .", "u | u u u . .|P|. u u u u u P<. .", "d | d d d .|B|. . d d d d d P<. .", "s | s s s s s . s s s s s .", "S | S S S S S S . S S S . .", "U | U U U U U U U . U . . .", "D | D D D D D D D D . . . .", "H | H H H H H H H ~U ~D . . .", "h | h h h h h h H ~U ~D S . .", "* | * * * * * h H ~U ~D S s .", }; Run(OpType::DIFFERENCE, PolygonModel::OPEN, rules); } TEST_F(DegeneracyCoverageTest, SemiOpenDifference) { // See SemiOpenUnion notes regarding (u,U) and (d,D). const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | . . . . . . . . . . . .", "p | p . .>p .>p .>p p p .>p .>p . . .", "P | P P . .>P .>P P P .>P .>P . . .", "u | u u u . .|P|. u u .|.|B u . . .", "d | d d d .|B|. . d d d .|B|PB . . .", "s | s s s s s . .>s .>s .>s .>s s .", "S | S S S S S S . . . S s<. .", "U | U U U U U U U . U . s<. .", "D | D D D D D D D D . . s<. .", "H | H H H H H H H ~U ~D . s<. .", "h | h h h h h h H ~U ~D S . .", "* | * * * * * h H ~U ~D S s .", }; Run(OpType::DIFFERENCE, PolygonModel::SEMI_OPEN, rules); } TEST_F(DegeneracyCoverageTest, ClosedDifference) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | . . . . . . . . . . . .", "p | p . .>p .>p .>p . . . . . . .", "P | P P . .>P .>P . . . . . . .", "u | u u u . .|P|. u . . . . . .", "d | d d d .|B|. . d . . . . . .", "s | s s s s s . . . . . s .", "S | S S S S S S . . . S . .", "U | U U U U U U U . U . . .", "D | D D D D D D D D . . . .", "H | H H H H H H H ~U ~D . . .", "h | h h h h h h H ~U ~D S . .", "* | * * * * * h H ~U ~D S s .", }; Run(OpType::DIFFERENCE, PolygonModel::CLOSED, rules); } TEST_F(DegeneracyCoverageTest, OpenSymmetricDifference) { const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | p .", "P | P Ph hP>h h H ~U ~D S .", "* | * * * * * h H ~U ~D S s .", }; Run(OpType::SYMMETRIC_DIFFERENCE, PolygonModel::OPEN, rules); } TEST_F(DegeneracyCoverageTest, SemiOpenSymmetricDifference) { // See SemiOpenUnion notes regarding (U,u) and (D,d). const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | p .", "P | P PH, (h,s)->h and (U,D)->UD. In all three cases the // shared boundary is present on both sides and therefore these edges should // not be contained by the result, however this is not possible under the // CLOSED model. The indicated results are the best approximation. const vector rules = { // . p P u d s S U D H h * // |----------------------------------------------------------------------- ". | .", "p | p .", "P | P P> loops{{S2Point(0, 0, -1), S2Point(-1, 0, 0), S2Point(0, 0, 1), S2Point(-1, 0, 0)}}; meridian.Add(make_unique(loops)); MutableS2ShapeIndex output; vector> layers(3); layers[0] = make_unique(&output); // TODO(ericv): Implement s2builderutil::IndexedS2LaxPolylineVectorLayer. layers[1] = make_unique(&output); layers[2] = make_unique(&output); S2BooleanOperation op(OpType::DIFFERENCE, std::move(layers)); S2Error error; ASSERT_TRUE(op.Build(*input, meridian, &error)) << error; EXPECT_EQ(expected_str, s2textformat::ToString(output)); } // This test demonstrates that S2 geometry can easily be transformed such that // no edge crosses the 180 degree meridian, as required by formats such as // GeoJSON, by simply subtracting a degenerate loop that follows the 180 degree // meridian. This not only splits polylines along the meridian, it also inserts // the necessary extra vertices at the north/south poles. (The only extra step // is that the vertices along the 180 degree meridian or at the poles may need // to be "doubled" into two vertices, one at longitude 180 and one at longitude // -180, in order to match the longitudes of the adjacent vertices.) TEST(S2BooleanOperation, MeridianSplitting) { // A line along the equator crossing the 180 degree meridian. TestMeridianSplitting("# 0:-160, 0:170 #", "# 0:-160, 0:180, 0:170 #"); // The northern hemisphere. TestMeridianSplitting("# # 0:0, 0:120, 0:-120", "# # 90:0, 0:180, 0:-120, 0:0, 0:120, 0:180"); // A small square that crosses the 180th meridian. Notice that one input // loop is split into two output loops. TestMeridianSplitting( "# # 9:179, 9:-179, 10:-179, 10:179", "# # 9.00134850712993:180, 9:-179, 10:-179, 10.0014925269841:180; " "10.0014925269841:180, 10:179, 9:179, 9.00134850712993:180"); // An annulus that crosses the 180th meridian. This turns into two shells. TestMeridianSplitting( "# # 8:178, 8:-178, 11:-178, 11:178; 9:179, 10:179, 10:-179, 9:-179", "# # 10.0014925269841:180, 10:-179, 9:-179, 9.00134850712993:180, " "8.00481316618607:180, 8:-178, 11:-178, 11.00654129428:180; " "9.00134850712993:180, 9:179, 10:179, 10.0014925269841:180, " "11.00654129428:180, 11:178, 8:178, 8.00481316618607:180"); // An annulus that crosses the 180th meridian. This turns into two shells. TestMeridianSplitting( "# # 8:178, 8:-178, 11:-178, 11:178; 9:179, 10:179, 10:-179, 9:-179", "# # 10.0014925269841:180, 10:-179, 9:-179, 9.00134850712993:180, " "8.00481316618607:180, 8:-178, 11:-178, 11.00654129428:180; " "9.00134850712993:180, 9:179, 10:179, 10.0014925269841:180, " "11.00654129428:180, 11:178, 8:178, 8.00481316618607:180"); // The whole world except for a small square that crosses the 180th meridian. // This is a single loop that visits both poles. The result is correct // except that (1) +180 or -180 needs to be chosen consistently with the // adjacent points, and (2) each pole needs to be duplicated (once with // longitude -180 and once with longitude 180). TestMeridianSplitting( "# # 9:-179, 9:179, 10:179, 10:-179", "# # 0:180, 9.00134850712993:180, 9:179, 10:179, 10.0014925269841:180, " "90:0, 10.0014925269841:180, 10:-179, 9:-179, 9.00134850712993:180, " "0:180, -90:0"); } void ComputeTestUnion(const vector>& a_loops, const vector>& b_loops, S1Angle snap_radius, S2LaxPolygonShape* result) { MutableS2ShapeIndex a, b; a.Add(make_unique(a_loops)); b.Add(make_unique(b_loops)); S2BooleanOperation op(OpType::UNION, make_unique(result), S2BooleanOperation::Options( s2builderutil::IdentitySnapFunction(snap_radius))); S2Error error; ASSERT_TRUE(op.Build(a, b, &error)) << error; EXPECT_FALSE(result->is_empty()) << "\nS2Polygon: " << s2textformat::ToString(a) << "\nS2Polygon: " << s2textformat::ToString(b); } TEST(S2BooleanOperation, GetCrossedVertexIndexBug1) { // This test exercises a rare special case in GetCrossedVertexIndex where // two crossing edge chains snap to a different permutation of the same // vertices. In this example one input edge crosses another edge from right // to left, the first edge snaps to BCD and the second snaps to ABDC, and // triangle BCD is CCW. Since BCD is to the right of BD, this means that // the first edge has not yet crossed the second at vertex B, leaving C or D // as the possible crossing vertices. vector> a_loops = { { {-0.38306437985388492, -0.74921955334206214, 0.54030708099846292}, {-0.3830643798552798, -0.74921955334134249, 0.5403070809984718}, {-0.38306437985529124, -0.74921955334136414, 0.54030708099843361}, {-0.38306437985389635, -0.74921955334208379, 0.54030708099842473}, }, }; vector> b_loops = { { {-0.38306437985390962, -0.74921955334210588, 0.54030708099838465}, {-0.38306437985527797, -0.74921955334134205, 0.54030708099847369}, {-0.38306437985527941, -0.74921955334134405, 0.54030708099847014}, {-0.38306437985391095, -0.74921955334210777, 0.54030708099838098}, }, }; S2LaxPolygonShape result; ComputeTestUnion(a_loops, b_loops, S2::kIntersectionMergeRadius, &result); } TEST(S2BooleanOperation, GetCrossedVertexIndexBug2) { // This test exercises another rare case where the crossing vertices chosen // by GetCrossedVertexIndex() are not ordered correctly along the edge being // crossed. This is handled by adding extra edges to the output in order to // link up the crossings in the correct order. vector> a_loops = { { {-0.3837392878495085, -0.7477800800281974, 0.5418201831546835}, {-0.38373928785696076, -0.7477800800212292, 0.54182018315902258}, {-0.38373928785701278, -0.74778008002124685, 0.5418201831589613}, {-0.38373928785703426, -0.7477800800212544, 0.54182018315893576}, {-0.38373947205489456, -0.74778014227795497, 0.5418199667802881}, {-0.38373947204434411, -0.74778014228781997, 0.54181996677414512}, {-0.38373947205872994, -0.74778014228185352, 0.54181996677219124}, {-0.38373947218468357, -0.74778014288930306, 0.54181996584462788}, {-0.3837396702525171, -0.74778021044361542, 0.54181973233114322}, {-0.38373967023137123, -0.74778021046333043, 0.54181973231891067}, {-0.38373947216030285, -0.74778014290791484, 0.54181996583620895}, {-0.38373947217087578, -0.74778014289805739, 0.54181996584232528}, {-0.38373947215649007, -0.74778014290402395, 0.54181996584427927}, {-0.3837394720305386, -0.74778014229658485, 0.5418199667718262}, {-0.38373928783585998, -0.74778008004095942, 0.54182018314673686}, {-0.38373928784641037, -0.7477800800310942, 0.54182018315287972}, {-0.38373928783578648, -0.74778008004093421, 0.54182018314682368}, {-0.383739287835765, -0.74778008004092666, 0.54182018314684921}, }, }; vector> b_loops = { { {-0.38373923813692823, -0.7477800632164362, 0.54182024156551456}, {-0.3837392878569364, -0.74778008002122087, 0.54182018315905123}, {-0.38373928784640354, -0.74778008003106944, 0.54182018315291858}, {-0.38373928784638789, -0.74778008003108642, 0.54182018315290648}, {-0.38373928784638023, -0.74778008003109453, 0.54182018315290048}, {-0.38373928783692102, -0.74778008004124585, 0.54182018314559}, {-0.38373928783691913, -0.74778008004124541, 0.54182018314559188}, {-0.38373928784636568, -0.74778008003110774, 0.54182018315289271}, {-0.38373928784637329, -0.74778008003109953, 0.54182018315289848}, {-0.38373928783583561, -0.74778008004095109, 0.5418201831467655}, {-0.38373923811582744, -0.74778006323616641, 0.54182024155322883}, {-0.38373857650312843, -0.74777983961840766, 0.54182101875399913}, {-0.38373857652422921, -0.74777983959867744, 0.54182101876628486}, }, }; S2LaxPolygonShape result; ComputeTestUnion(a_loops, b_loops, S2::kIntersectionMergeRadius, &result); } TEST(S2BooleanOperation, GetCrossedVertexIndexBug3) { // This test exercises the special case in GetCrossedVertexIndex() that // requires checking the orientation of a loop. This is done by adding up the // turning angles at each vertex, which in turn involves computing the edge // normals and measuring the angles between them. However in this test, some // of the edge normals returned by S2::RobustCrossProd() used to be so small // that there were floating-point underflows when computing the angles between // them. This was fixed by implementing the long-standing TODO of making // S2::RobustCrossProd() actually robust. vector> a_loops = { { {1, 0, 2.4678234835261742e-72}, {0.99984769515639127, 0.017452406437283512, 1.8530922845942552e-27}, {0.99740259703611311, 0.069881849826437858, 0.017452406437283512}, }, }; vector> b_loops = { { {0.99999999999999989, 2.4674476220564615e-72, 2.4678234835261742e-72}, {0.99999999999999989, 2.8837981406657438e-169, 2.4678234835261742e-72}, {1, 2.8837981406657432e-169, 2.4678234835261742e-72}, }, }; S2LaxPolygonShape result; ComputeTestUnion(a_loops, b_loops, S1Angle::Zero(), &result); } TEST(S2BooleanOperation, GetCrossedVertexIndexBug4) { // This example tests the "special case" in GetCrossedVertexIndex() in // situations where two edges snap to the same sequence of vertices in // different orders. The first two edges (a0, a1) and (b0, b1) of the // following polygons cross such that after snapping, the corresponding edge // chains are: // // a0 a1 -> a0 b0 b1 x a1 // b0 b1 -> b0 x b1 // // where "x" is the computed intersection point of (a0, a1) and (b0, b1). // Previously there was a bug such that the two edge chains did not choose // the same vertex to represent the point where the two chains cross: the // (a0, a1) chain chose "x" as the crossing point while the (b0, b1) chain // chose "b0". This has been fixed such that both chains now choose "x". // (Both "x" and "b1" happen to be valid choices in this example, but it is // essential that both subchains make the same choice.) // S2LatLng coordinates are not accurate enough to reproduce this example. vector> a_loops{{ // 51.5131559470858:-0.130381523356724 {0.62233331065911901, -0.0014161759526823048, 0.78275107466533156}, // 51.5131892038956:-0.130404244210776 {0.6223328557578689, -0.0014164217071954736, 0.78275143589379825}, s2textformat::MakePointOrDie("51.51317:-0.1306") }}; vector> b_loops{{ // 51.5131559705551:-0.13038153939079 {0.62233331033809591, -0.001416176126110953, 0.78275107492024998}, // 51.5131559705551:-0.130381539390786 {0.62233331033809591, -0.0014161761261109063, 0.78275107492025009}, s2textformat::MakePointOrDie("51.52:-0.12"), s2textformat::MakePointOrDie("51.52:-0.14") }}; S2LaxPolygonShape result; ComputeTestUnion(a_loops, b_loops, S1Angle::Zero(), &result); } TEST(S2BooleanOperation, GetCrossedVertexIndexBug5) { // Yet another bizarre situation where two crossing edges snap (correctly) to // a sequence of vertices in different orders. Using the internal vertex // numbers assigned by S2Builder, input edges 3 and 12 snap to the following // vertex sequences: // // Input edge 3: 14, 8, 4, 9, 2, 5 // Input edge 12: 2, 7, 8, 9 // // Furthermore input edge 3 crosses input edge 12 from left to right. // Schematically, here is what edge 12 crossing edge 3 looks like: // // 14-->--8-->--4-->--9-->--2-->--5 // |\ / / // \ \--->---/ / // \ / // \--<--7--<--/ // // And here is what edge 3 crossing edge 12 looks like: // // 14-->--\ /---4->-\ // \ / \ // 2-->--7-->--8----->-----9 // / \ / // 5--<--/ \---------<---------/ // // In both cases, the only possible choice of crossing vertex consistent with // the fact that edge 3 crosses edge 12 from left to right is vertex 9. // Determining this requires knowing that loop (9, 2, 7, 8) is clockwise // (the "special case" in GetCrossedVertexIndex). The code previously didn't // have quite the correct test to decide when this was necessary. vector> a_loops = { { {0.99984769515639127, 0, 0.017452406437283512}, {0.99923861495548261, 0.017441774902830158, 0.034899496702500969}, {0.99847743863945992, 0.052327985223313139, 0.017452406437283512}, {0.99802119662406841, 0.034851668155187324, 0.052335956242943835}, }, }; vector> b_loops = { { {0.99802119662406841, 0.034851668155187324, 0.052335956242943835}, {0.99619692339885657, 0.052208468483931986, 0.069756473744125302}, {0.99802098681615425, 0.034839714972148959, 0.052347914334467859}, {0.99741208276778681, 0.017411821260589495, 0.069756473744125302}, {0.99741219210106513, 0.017411340538768819, 0.069755030419252628}, {0.99741211642315963, 0.017409893252357169, 0.069756473744125302}, {0.99984769515639116, 4.9500424645560228e-16, 0.017452406437284993}, {0.99984769515639127, 3.7368529835165677e-16, 0.017452406437284632}, {0.99984769515639116, 3.3065924905014365e-16, 0.017452406437284504}, {0.99984769515639127, 9.9060035932242025e-16, 0.017452406437284504}, {0.99969541350954794, 0.017449748351250485, 0.017452406437283512}, }, { {0.99984769515639116, 3.3065924905014365e-16, 0.017452406437284504}, {0.99984769515639116, 3.3006856770496304e-16, 0.017452406437284504}, {0.99984769515639127, 0, 0.017452406437284504}, {0.99984769515639127, 0, 0.017452406437283512}, }, }; S2LaxPolygonShape result; ComputeTestUnion(a_loops, b_loops, S1Angle::Zero(), &result); } TEST(S2BooleanOperation, GetCrossedVertexIndexBug6) { // This is another test of the code in GetCrossedVertexIndex() that checks // whether the B subchain contains an interior vertex of the A edge. vector> a_loops = { { {0.99870488823558456, 0.026138065586168355, 0.043650289137205818}, {0.99876259434149239, 0.030513215246694664, 0.0392711578586665}, {0.99984769515639127, 0.017452406437283512, 0}, {0.998782023517925, 0.034862286684437908, 0.034915476003791211}, {0.99878202512991221, 0.034878236872062651, 0.034899496702500969}, {0.9975640502598242, 0.069756473744125302, 0}, {0.99877979583714305, 0.034883478425067296, 0.034958008531414335}, {0.99619692339885657, 0.052208468483931986, 0.069756473744125302}, {0.99847581234813876, 0.017465633646566288, 0.052354596713645812}, {0.9975640502598242, 0, 0.069756473744125302}, {0.99847674250410212, 0.017444393356200013, 0.052343937746706169}, {0.99847743863945992, 0.017428488520812163, 0.052335956242943835}, {0.99984769515639127, 0, 0.017452406437283512}, }, { {0.99619692339885657, 0.052208468483931986, 0.069756473744125302}, {0.99802119661969568, 0.034851668280404598, 0.052335956242943835}, {0.9987605225894034, 0.030527121154938986, 0.039313018084772409}, {0.99870321796526884, 0.026161932439896601, 0.043674199670139441}, }, { {0.99619692339885657, 0.052208468483931986, 0.069756473744125302}, {0.99619692339885657, 0.06966087492121549, 0.052335956242943835}, {0.99513403437078507, 0.069586550480032719, 0.069756473744125302}, }, }; vector> b_loops = { { {0.99802200429988497, 0.034828499898458924, 0.052335977377554299}, {0.99862953475457383, 0, 0.052335956242943835}, {0.99923793061512223, 0.017455729388178846, 0.034912111530741322}, {0.99923859085845868, 0.017443155365764275, 0.034899496702500969}, {0.99923793076147094, 0.017455737780810811, 0.034912103145779166}, {0.9992865072388355, 0.020934110218524152, 0.0314362764933699}, {1, 0, 0}, {0.99929987808789411, 0.022418034384064717, 0.029953053064335624}, {0.99931406232431441, 0.02616995393092059, 0.026201876881811362}, {0.99984769515639127, 0.017452406437283512, 0}, {0.99930573320200933, 0.029072747464899757, 0.023298646837028814}, {0.99862953475457383, 0.052335956242943835, 1.700986599320836e-73}, {0.99838518277004218, 0.038347188759395717, 0.041910857059723181}, {0.99619692339885668, 0.052208468483931979, 0.069756473744125289}, }, { {0.99802119662406841, 0.052304074592470849, 0.034899496702500969}, {0.99847743834686298, 0.052327990806397578, 0.017452406437283512}, {0.99619645281505653, 0.052208443821680058, 0.069763212314351342}, {0.99619692339885657, 0.052208468483932, 0.069756473744125316}, {0.99619692339885657, 0.052208468483931986, 0.069756473744125302}, {0.99619692339885679, 0.052208468483931993, 0.069756473744125316}, {0.99619692339885679, 0.052208468483931986, 0.069756473744125302}, {0.99619692339885668, 0.052208468483931979, 0.069756473744125289}, }, }; S2LaxPolygonShape result; ComputeTestUnion(a_loops, b_loops, S1Angle::Zero(), &result); } // Performs the given operation and compares the result to "expected_str". All // arguments are in s2textformat::MakeLaxPolygonOrDie() format. void ExpectPolygon(S2BooleanOperation::OpType op_type, string_view a_str, string_view b_str, string_view expected_str) { auto a = s2textformat::MakeIndexOrDie(StrCat("# # ", a_str)); auto b = s2textformat::MakeIndexOrDie(StrCat("# # ", b_str)); s2builderutil::LaxPolygonLayer::Options polygon_options; polygon_options.set_degenerate_boundaries(DegenerateBoundaries::DISCARD); S2LaxPolygonShape output; S2BooleanOperation op( op_type, make_unique(&output, polygon_options), S2BooleanOperation::Options{s2builderutil::IdentitySnapFunction{ S1Angle::Degrees(1.1)}}); S2Error error; ASSERT_TRUE(op.Build(*a, *b, &error)) << error; EXPECT_EQ(expected_str, s2textformat::ToString(output)); } TEST(S2BooleanOperation, FullAndEmptyResults) { // The following constants are all in s2textformat::MakeLaxPolygonOrDie() // format. string kEmpty = ""; string kFull = "full"; // Two complementary shell/hole pairs, together with alternative shells that // are slightly smaller or larger than the original. string kShell1 = "10:0, 10:10, 20:10"; string kHole1 = "10:0, 20:10, 10:10"; string kShell1Minus = "11:2, 11:9, 18:9"; string kShell1Plus = "9:-2, 9:11, 22:11"; string kShell2 = "10:20, 10:30, 20:30"; string kHole2 = "10:20, 20:30, 10:30"; // The northern and southern hemispheres. string kNorthHemi = "0:0, 0:120, 0:-120"; string kSouthHemi = "0:0, 0:-120, 0:120"; // These edges deviate from kSouthHemi by slightly more than 1 degree. string kSouthHemiPlus = "0.5:0, 0.5:-120, 0.5:120"; // A shell and hole that cover complementary hemispheres, such that each // hemisphere intersects all six S2 cube faces. There are also alternative // shells that are slightly smaller or larger than the original. string k6FaceShell1 = "0:-45, 45:0, 45:90, 0:135, -45:180, -45:-90"; string k6FaceHole1 = "0:-45, -45:-90, -45:180, 0:135, 45:90, 45:0"; string k6FaceShell1Minus = "-1:-45, 44:0, 44:90, -1:135, -46:180, -46:-90"; string k6FaceShell1Plus = "1:-45, 46:0, 46:90, 1:135, -44:180, -44:-90"; // Two complementary shell/hole pairs that are small enough so that they will // disappear when the snap radius chosen above is used. string kAlmostEmpty1 = "2:0, 2:10, 3:0"; string kAlmostFull1 = "2:0, 3:0, 2:10"; string kAlmostEmpty2 = "4:0, 4:10, 5:0"; string kAlmostFull2 = "4:0, 5:0, 4:10"; // A polygon that intersects all 6 faces such but snaps to an empty polygon. string k6FaceAlmostEmpty1 = k6FaceShell1Minus + "; " + k6FaceHole1; // Test empty UNION results. // - Exact result, no input edges. ExpectPolygon(OpType::UNION, kEmpty, kEmpty, kEmpty); // - Empty due to snapping, union does not intersect all 6 cube faces. ExpectPolygon(OpType::UNION, kAlmostEmpty1, kAlmostEmpty2, kEmpty); // - Empty due to snapping, union intersects all 6 cube faces. ExpectPolygon(OpType::UNION, k6FaceAlmostEmpty1, k6FaceAlmostEmpty1, kEmpty); // Test full UNION results. // - Exact result, no input edges. ExpectPolygon(OpType::UNION, kEmpty, kFull, kFull); ExpectPolygon(OpType::UNION, kEmpty, kFull, kFull); ExpectPolygon(OpType::UNION, kFull, kFull, kFull); // - Exact result, some input edges. ExpectPolygon(OpType::UNION, kFull, kShell1, kFull); ExpectPolygon(OpType::UNION, kHole1, kHole2, kFull); ExpectPolygon(OpType::UNION, kHole1, kShell1, kFull); // - Full due to snapping, almost complementary polygons. ExpectPolygon(OpType::UNION, kHole1, kShell1Minus, kFull); ExpectPolygon(OpType::UNION, k6FaceHole1, k6FaceShell1Minus, kFull); // Test empty INTERSECTION results. // - Exact result, no input edges. ExpectPolygon(OpType::INTERSECTION, kEmpty, kEmpty, kEmpty); ExpectPolygon(OpType::INTERSECTION, kEmpty, kFull, kEmpty); ExpectPolygon(OpType::INTERSECTION, kFull, kEmpty, kEmpty); // - Exact result, inputs do not both intersect all 6 cube faces. ExpectPolygon(OpType::INTERSECTION, kEmpty, kHole1, kEmpty); ExpectPolygon(OpType::INTERSECTION, kShell1, kShell2, kEmpty); ExpectPolygon(OpType::INTERSECTION, kShell1, kHole1, kEmpty); // - Exact result, inputs both intersect all 6 cube faces. ExpectPolygon(OpType::INTERSECTION, k6FaceShell1, k6FaceHole1, kEmpty); // - Empty due to snapping, inputs do not both intersect all 6 cube faces. ExpectPolygon(OpType::INTERSECTION, kShell1Plus, kHole1, kEmpty); // - Empty due to snapping, inputs both intersect all 6 cube faces. ExpectPolygon(OpType::INTERSECTION, k6FaceShell1Plus, k6FaceHole1, kEmpty); // Test full INTERSECTION results. // - Exact result, no input edges. ExpectPolygon(OpType::INTERSECTION, kFull, kFull, kFull); // - Full due to snapping, almost full input polygons. ExpectPolygon(OpType::INTERSECTION, kAlmostFull1, kAlmostFull2, kFull); // Test empty DIFFERENCE results. // - Exact result, no input edges. ExpectPolygon(OpType::DIFFERENCE, kEmpty, kEmpty, kEmpty); ExpectPolygon(OpType::DIFFERENCE, kEmpty, kFull, kEmpty); ExpectPolygon(OpType::DIFFERENCE, kFull, kFull, kEmpty); // - Exact result, first input does not intersect all 6 cube faces. ExpectPolygon(OpType::DIFFERENCE, kEmpty, kShell1, kEmpty); ExpectPolygon(OpType::DIFFERENCE, kShell1, kFull, kEmpty); ExpectPolygon(OpType::DIFFERENCE, kShell1, kShell1, kEmpty); ExpectPolygon(OpType::DIFFERENCE, kShell1, kHole2, kEmpty); // - Exact result, first input intersects all 6 cube faces. ExpectPolygon(OpType::DIFFERENCE, k6FaceShell1, k6FaceShell1Plus, kEmpty); // - Empty due to snapping, first input does not intersect all 6 cube faces. ExpectPolygon(OpType::DIFFERENCE, kShell1Plus, kShell1, kEmpty); // - Empty due to snapping, first input intersect all 6 cube faces. ExpectPolygon(OpType::DIFFERENCE, k6FaceShell1Plus, k6FaceShell1, kEmpty); // Test full DIFFERENCE results. // - Exact result, no input edges. ExpectPolygon(OpType::DIFFERENCE, kFull, kEmpty, kFull); // - Full due to snapping, almost full/empty input polygons. ExpectPolygon(OpType::DIFFERENCE, kAlmostFull1, kAlmostEmpty2, kFull); // Test empty SYMMETRIC_DIFFERENCE results. // - Exact result, no input edges. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kEmpty, kEmpty, kEmpty); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kFull, kFull, kEmpty); // - Exact result, union does not intersect all 6 cube faces. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kShell1, kShell1, kEmpty); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kNorthHemi, kNorthHemi, kEmpty); // - Exact result, union intersects all 6 cube faces. This case is only // handled correctly due to the kBiasTowardsEmpty heuristic. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, k6FaceShell1, k6FaceShell1, kEmpty); // - Empty due to snapping, union does not intersect all 6 cube faces. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kShell1Plus, kShell1, kEmpty); // - Empty due to snapping, union intersects all 6 cube faces. This case is // only handled correctly due to the kBiasTowardsEmpty heuristic. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, k6FaceShell1Plus, k6FaceShell1, kEmpty); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, k6FaceShell1Minus, k6FaceShell1, kEmpty); // Test full SYMMETRIC_DIFFERENCE results. // - Exact result, no input edges. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kFull, kEmpty, kFull); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kEmpty, kFull, kFull); // - Exact result, complementary input polygons. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kShell1, kHole1, kFull); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kAlmostEmpty1, kAlmostFull1, kFull); // - Full due to snapping, almost complementary input polygons. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kShell1Plus, kHole1, kFull); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kAlmostFull1, kAlmostEmpty2, kFull); // - Exact result, complementary hemispheres, at least one input does not // intersect all 6 cube faces. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kNorthHemi, kSouthHemi, kFull); // - Exact result, almost complementary hemispheres, at least one input does // not intersect all 6 cube faces. ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, kNorthHemi, kSouthHemiPlus, kFull); // TODO(ericv): The following case is not currently implemented. // - Full result, complementary (to within the snap radius) input polygons // each with an area of approximately 2*Pi, and both polygons intersect all // 6 cube faces. #if 0 ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, k6FaceShell1, k6FaceHole1, kFull); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, k6FaceShell1Plus, k6FaceHole1, kFull); ExpectPolygon(OpType::SYMMETRIC_DIFFERENCE, k6FaceShell1Minus, k6FaceHole1, kFull); #endif } // Tests whether the two S2ShapeIndexes are equal according to // S2BooleanOperation::Equals(). bool TestEqual(string_view a_str, string_view b_str) { auto a = s2textformat::MakeIndexOrDie(a_str); auto b = s2textformat::MakeIndexOrDie(b_str); return S2BooleanOperation::Equals(*a, *b); } // Tests S2BooleanOperation::Equals, which computes the symmetric difference // between two geometries and tests whether the result is empty. // // This also indirectly tests IsEmpty(), which is used to implement Contains() // and Intersects(). TEST(S2BooleanOperation, Equals) { EXPECT_TRUE(TestEqual("# #", "# #")); EXPECT_TRUE(TestEqual("# # full", "# # full")); EXPECT_FALSE(TestEqual("# #", "# # full")); EXPECT_FALSE(TestEqual("0:0 # #", "# #")); EXPECT_FALSE(TestEqual("0:0 # #", "# # full")); EXPECT_FALSE(TestEqual("# 0:0, 1:1 #", "# #")); EXPECT_FALSE(TestEqual("# 0:0, 1:1 #", "# # full")); EXPECT_FALSE(TestEqual("# # 0:0, 0:1, 1:0 ", "# #")); EXPECT_FALSE(TestEqual("# # 0:0, 0:1, 1:0 ", "# # full")); } // Tests Contains() on empty and full geometries. TEST(S2BooleanOperation, ContainsEmptyAndFull) { auto empty = s2textformat::MakeIndexOrDie("# #"); auto full = s2textformat::MakeIndexOrDie("# # full"); EXPECT_TRUE(S2BooleanOperation::Contains(*empty, *empty)); EXPECT_FALSE(S2BooleanOperation::Contains(*empty, *full)); EXPECT_TRUE(S2BooleanOperation::Contains(*full, *empty)); EXPECT_TRUE(S2BooleanOperation::Contains(*full, *full)); } // Tests Intersects() on empty and full geometries. TEST(S2BooleanOperation, IntersectsEmptyAndFull) { auto empty = s2textformat::MakeIndexOrDie("# #"); auto full = s2textformat::MakeIndexOrDie("# # full"); EXPECT_FALSE(S2BooleanOperation::Intersects(*empty, *empty)); EXPECT_FALSE(S2BooleanOperation::Intersects(*empty, *full)); EXPECT_FALSE(S2BooleanOperation::Intersects(*full, *empty)); EXPECT_TRUE(S2BooleanOperation::Intersects(*full, *full)); } TEST(S2BooleanOperation, OptionsFieldsCopied) { S2BooleanOperation::Options options; // Just test one field. options.set_polyline_loops_have_boundaries(false); S2BooleanOperation no_boundary_op(S2BooleanOperation::OpType::UNION, vector>(), options); EXPECT_FALSE(no_boundary_op.options().polyline_loops_have_boundaries()); options.set_polyline_loops_have_boundaries(true); S2BooleanOperation boundary_op(S2BooleanOperation::OpType::UNION, vector>(), options); EXPECT_TRUE(boundary_op.options().polyline_loops_have_boundaries()); } TEST(S2BooleanOperationSourceIdTest, Accessors) { // region_id may only be 0 or 1. S2BooleanOperation::SourceId id(/*region_id=*/1, /*shape_id=*/2, /*edge_id=*/3); EXPECT_EQ(1, id.region_id()); EXPECT_EQ(2, id.shape_id()); EXPECT_EQ(3, id.edge_id()); } TEST(S2BooleanOperationSourceIdTest, Equality) { using Id = S2BooleanOperation::SourceId; EXPECT_EQ(Id(1, 2, 3), Id(1, 2, 3)); // `operator!=` is not defined, so use `==` instead of `EXPECT_NE`. EXPECT_FALSE(Id(1, 2, 3) == Id(0, 2, 3)); EXPECT_FALSE(Id(1, 2, 3) == Id(1, 0, 3)); EXPECT_FALSE(Id(1, 2, 3) == Id(1, 2, 0)); } TEST(S2BooleanOperationSourceIdTest, LessThan) { using Id = S2BooleanOperation::SourceId; EXPECT_FALSE(Id(1, 2, 3) < Id(1, 2, 3)); EXPECT_LT(Id(0, 2, 3), Id(1, 2, 3)); EXPECT_LT(Id(1, 2, 3), Id(1, 20, 3)); EXPECT_LT(Id(1, 2, 3), Id(1, 2, 30)); } } // namespace src/s2/s2buffer_operation.cc000066400000000000000000000761341524103652300163120ustar00rootroot00000000000000// Copyright 2020 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) // // The algorithm below essentially computes the offset curve of the original // boundary, and uses this curve to divide the sphere into regions of constant // winding number. Since winding numbers on the sphere are relative rather // than absolute (see s2winding_operation.h), we also need to keep track of // the desired winding number at a fixed reference point. The initial winding // number for this point is the number of input shapes that contain it. We // then update it during the buffering process by imagining a "sweep edge" // that extends from the current point A on the input boundary to the // corresponding point B on the offset curve. As we process an input loop and // generate the corresponding offset curve, the sweep edge moves continuously // and covers the entire buffer region (i.e., the region added to or // subtracted from the input geometry). We increase the winding number of the // reference point by one whenever it crosses the sweep edge from left to // right, and we decrease the winding number by one whenever it crosses the // sweep edge from right to left. // // Concave vertices require special handling, because the corresponding offset // curve can leave behind regions whose winding number is zero or negative. // We handle this by splicing the concave vertex into the offset curve itself; // this effectively terminates the current buffer region and starts a new one, // such that the region of overlap is counted twice (i.e., its winding number // increases by two). The end result is the same as though we had computed // the union of a sequence of buffered convex boundary segments. This trick // is described in the following paper: "Polygon Offsetting by Computing // Winding Numbers" (Chen and McMains, Proceedings of IDETC/CIE 2005). // // TODO(ericv): The algorithm below is much faster than, say, computing the // union of many buffered edges. However further improvements are possible. // In particular, there is an unimplemented optimization that would make it // much faster to buffer concave boundaries when the buffer radius is large. #include "s2/s2buffer_operation.h" #include #include #include #include #include #include #include "absl/base/nullability.h" #include "absl/log/absl_check.h" #include "absl/types/span.h" #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2builder.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_snap_functions.h" #include "s2/s2contains_point_query.h" #include "s2/s2edge_crosser.h" #include "s2/s2edge_crossings.h" #include "s2/s2edge_distances.h" #include "s2/s2error.h" #include "s2/s2lax_loop_shape.h" #include "s2/s2memory_tracker.h" #include "s2/s2point.h" #include "s2/s2point_span.h" #include "s2/s2pointutil.h" #include "s2/s2predicates.h" #include "s2/s2predicates_internal.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2shape_measures.h" #include "s2/s2shapeutil_contains_brute_force.h" #include "s2/s2winding_operation.h" #include "s2/util/math/mathutil.h" using s2pred::DBL_ERR; using std::ceil; using std::make_unique; using std::max; using std::min; using std::unique_ptr; using std::vector; // The errors due to buffering can be categorized as follows: // // 1. Requested error. This represents the error due to approximating the // buffered boundary as a sequence of line segments rather than a sequence // of circular arcs. It is largely controlled by options.error_fraction(), // and can be bounded as // // max(kMinRequestedError, error_fraction * buffer_radius) // // where kMinRequestedError reflects the fact that S2Points do not have // infinite precision. (For example, it makes no sense to attempt to // buffer geometry by 1e-100 radians because the spacing between // representable S2Points is only about 2e-16 radians in general.) // // 2. Relative interpolation errors. These are numerical errors whose // magnitude is proportional to the buffer radius. For such errors the // worst-case coefficient of proportionality turns out to be so tiny // compared to the smallest allowable error fraction (kMinErrorFraction) // that we simply ignore such errors. // // 3. Absolute interpolation errors. These are numerical errors that are not // proportional to the buffer radius. The main sources of such errors are // (1) calling S2::RobustCrossProd() to compute edge normals, and (2) calls // to S2::GetPointOnRay() to interpolate points along the buffered // boundary. It is possible to show that this error is at most // kMaxAbsoluteInterpolationError as defined below. // // Putting these together, the final error bound looks like this: // // max_error = kMaxAbsoluteInterpolationError + // max(kMinRequestedError, // max(kMinErrorFraction, options.error_fraction()) * // options.buffer_radius()) // The maximum angular spacing between representable S2Points on the unit // sphere is roughly 2 * DBL_ERR. We require the requested absolute error to // be at least this large because attempting to achieve a smaller error does // not increase the precision of the result and can increase the running time // and space requirements considerably. static constexpr S1Angle kMinRequestedError = S1Angle::Radians(2 * DBL_ERR); // The maximum absolute error due to interpolating points on the buffered // boundary. The following constant bounds the maximum additional error // perpendicular to the buffered boundary due to all steps of the calculation // (S2::RobustCrossProd, the two calls to GetPointOnRay, etc). // // This distance represents about 10 nanometers on the Earth's surface. Note // that this is a conservative upper bound and that it is difficult to // construct inputs where the error is anywhere close to this large. static constexpr S1Angle kMaxAbsoluteInterpolationError = S2::kGetPointOnLineError + S2::kGetPointOnRayPerpendicularError; S2BufferOperation::Options::Options() : snap_function_( make_unique(S1Angle::Zero())) { } S2BufferOperation::Options::Options(S1Angle buffer_radius) : Options() { buffer_radius_ = buffer_radius; } S2BufferOperation::Options::Options(const Options& options) : buffer_radius_(options.buffer_radius_), error_fraction_(options.error_fraction_), end_cap_style_(options.end_cap_style_), polyline_side_(options.polyline_side_), snap_function_(options.snap_function_->Clone()), memory_tracker_(options.memory_tracker_) { } S2BufferOperation::Options& S2BufferOperation::Options::operator=( const Options& options) { buffer_radius_ = options.buffer_radius_; error_fraction_ = options.error_fraction_; end_cap_style_ = options.end_cap_style_; polyline_side_ = options.polyline_side_; snap_function_ = options.snap_function_->Clone(); memory_tracker_ = options.memory_tracker_; return *this; } S1Angle S2BufferOperation::Options::buffer_radius() const { return buffer_radius_; } void S2BufferOperation::Options::set_buffer_radius(S1Angle buffer_radius) { buffer_radius_ = buffer_radius; } double S2BufferOperation::Options::error_fraction() const { return error_fraction_; } void S2BufferOperation::Options::set_error_fraction(double error_fraction) { ABSL_DCHECK_GE(error_fraction, kMinErrorFraction); ABSL_DCHECK_LE(error_fraction, 1.0); error_fraction_ = max(kMinErrorFraction, min(1.0, error_fraction)); } S1Angle S2BufferOperation::Options::max_error() const { // See comments for kMinRequestedError above. S2Builder::Options builder_options(*snap_function_); builder_options.set_split_crossing_edges(true); return max(kMinRequestedError, error_fraction_ * abs(buffer_radius_)) + kMaxAbsoluteInterpolationError + builder_options.max_edge_deviation(); } double S2BufferOperation::Options::circle_segments() const { #if 0 // This formula assumes that vertices can be placed anywhere. TODO(ericv). return M_PI / acos((1 - error_fraction_) / (1 + error_fraction_)); #else // This formula assumes that all vertices are placed on the midline. return M_PI / acos(1 - error_fraction_); #endif } void S2BufferOperation::Options::set_circle_segments(double circle_segments) { ABSL_DCHECK_GE(circle_segments, 2.0); ABSL_DCHECK_LE(circle_segments, kMaxCircleSegments); circle_segments = max(2.0, min(kMaxCircleSegments, circle_segments)); // We convert circle_segments to error_fraction using planar geometry, // because the number of segments required to approximate a circle on the // sphere to within a given tolerance is not constant. Unlike in the plane, // the total curvature of a circle on the sphere decreases as the area // enclosed by the circle increases; great circles have no curvature at all. // We round up when converting to ensure that we won't generate any tiny // extra edges. // #if 0 // Note that we take advantage of both positive and negative errors when // approximating circles (i.e., vertices are not necessarily on the midline) // and thus the relationships between circle_segments and error_fraction are // e = (1 - cos(Pi/n)) / (1 + cos(Pi/n)) // n = Pi / acos((1 - e) / (1 + e)) double r = cos(M_PI / circle_segments); set_error_fraction((1 - r) / (1 + r) + 1e-15); #else // When all vertices are on the midline, the relationships are // e = 1 - cos(Pi/n) // n = Pi / acos(1 - e) set_error_fraction(1 - cos(M_PI / circle_segments) + 1e-15); #endif } S2BufferOperation::EndCapStyle S2BufferOperation::Options::end_cap_style() const { return end_cap_style_; } void S2BufferOperation::Options::set_end_cap_style(EndCapStyle end_cap_style) { end_cap_style_ = end_cap_style; } S2BufferOperation::PolylineSide S2BufferOperation::Options::polyline_side() const { return polyline_side_; } void S2BufferOperation::Options::set_polyline_side( PolylineSide polyline_side) { polyline_side_ = polyline_side; } const S2Builder::SnapFunction& S2BufferOperation::Options::snap_function() const { return *snap_function_; } void S2BufferOperation::Options::set_snap_function( const S2Builder::SnapFunction& snap_function) { snap_function_ = snap_function.Clone(); } S2MemoryTracker* S2BufferOperation::Options::memory_tracker() const { return memory_tracker_; } void S2BufferOperation::Options::set_memory_tracker(S2MemoryTracker* tracker) { memory_tracker_ = tracker; } S2BufferOperation::S2BufferOperation() = default; S2BufferOperation::S2BufferOperation(unique_ptr result_layer, const Options& options) { Init(std::move(result_layer), options); } void S2BufferOperation::Init(unique_ptr result_layer, const Options& options) { options_ = options; ref_point_ = S2::Origin(); ref_winding_ = 0; have_input_start_ = false; have_offset_start_ = false; buffer_sign_ = sgn(options_.buffer_radius().radians()); S1Angle abs_radius = abs(options_.buffer_radius()); S1Angle requested_error = max(kMinRequestedError, options_.error_fraction() * abs_radius); S1Angle max_error = kMaxAbsoluteInterpolationError + requested_error; if (abs_radius <= max_error) { // If the requested radius is smaller than the maximum error, buffering // could yield points on the wrong side of the original input boundary // (e.g., shrinking geometry slightly rather than expanding it). Rather // than taking that risk, we set the buffer radius to zero when this // happens (which causes the original geometry to be returned). abs_radius_ = S1ChordAngle::Zero(); buffer_sign_ = 0; } else if (abs_radius + max_error >= S1Angle::Radians(M_PI)) { // If the permissible range of buffer angles includes Pi then we might // as well take advantage of that. abs_radius_ = S1ChordAngle::Straight(); } else { abs_radius_ = S1ChordAngle(abs_radius); S1Angle vertex_step = GetMaxEdgeSpan(abs_radius, requested_error); vertex_step_ = S1ChordAngle(vertex_step); // We take extra care to ensure that points are buffered as regular // polygons. The step angle is adjusted up slightly to ensure that we // don't wind up with a tiny extra edge. point_step_ = S1ChordAngle::Radians( 2 * M_PI / ceil(2 * M_PI / vertex_step.radians()) + 1e-15); // Edges are buffered only if the buffer radius (including permissible // error) is less than 90 degrees. S1Angle edge_radius = S1Angle::Radians(M_PI_2) - abs_radius; if (edge_radius > max_error) { edge_step_ = S1ChordAngle(GetMaxEdgeSpan(edge_radius, requested_error)); } } // The buffered output should include degeneracies (i.e., isolated points // and/or sibling edge pairs) only if (1) the user specified a non-negative // buffer radius, and (2) the adjusted buffer radius is zero. The only // purpose of keeping degeneracies is to allow points/polylines in the input // geometry to be converted back to points/polylines in the output if the // client so desires. S2WindingOperation::Options winding_options{options.snap_function()}; winding_options.set_include_degeneracies( buffer_sign_ == 0 && options_.buffer_radius() >= S1Angle::Zero()); winding_options.set_memory_tracker(options.memory_tracker()); op_.Init(std::move(result_layer), winding_options); tracker_.Init(options.memory_tracker()); } const S2BufferOperation::Options& S2BufferOperation::options() const { return options_; } S1Angle S2BufferOperation::GetMaxEdgeSpan(S1Angle radius, S1Angle requested_error) const { // If the allowable radius range spans Pi/2 then we can use edges as long as // we like, however we always use at least 3 edges to approximate a circle. S1Angle step = S1Angle::Radians(2 * M_PI / 3 + 1e-15); S1Angle min_radius = radius - requested_error; ABSL_DCHECK_GE(min_radius, S1Angle::Zero()); if (radius.radians() < M_PI_2) { step = min(step, S1Angle::Radians(2 * acos(tan(min_radius) / tan(radius)))); } else if (min_radius.radians() > M_PI_2) { step = min(step, S1Angle::Radians(2 * acos(tan(radius) / tan(min_radius)))); } return step; } // The sweep edge AB (see introduction) consists of one point on the input // boundary (A) and one point on the offset curve (B). This function advances // the sweep edge by moving its first vertex A to "new_a" and updating the // winding number of the reference point if necessary. void S2BufferOperation::SetInputVertex(const S2Point& new_a) { if (have_input_start_) { ABSL_DCHECK(have_offset_start_); UpdateRefWinding(sweep_a_, sweep_b_, new_a); } else { input_start_ = new_a; have_input_start_ = true; } sweep_a_ = new_a; } // Adds the point "new_b" to the offset path. Also advances the sweep edge AB // by moving its second vertex B to "new_b" and updating the winding number of // the reference point if necessary (see introduction). void S2BufferOperation::AddOffsetVertex(const S2Point& new_b) { if (!tracker_.AddSpace(&path_, 1)) return; path_.push_back(new_b); if (have_offset_start_) { ABSL_DCHECK(have_input_start_); UpdateRefWinding(sweep_a_, sweep_b_, new_b); } else { offset_start_ = new_b; have_offset_start_ = true; } sweep_b_ = new_b; } // Finishes buffering the current loop by advancing the sweep edge back to its // starting location, updating the winding number of the reference point if // necessary. void S2BufferOperation::CloseBufferRegion() { if (have_offset_start_ && have_input_start_) { UpdateRefWinding(sweep_a_, sweep_b_, input_start_); UpdateRefWinding(input_start_, sweep_b_, offset_start_); } } // Outputs the current buffered path (which is assumed to be a loop), and // resets the state to prepare for buffering a new loop. void S2BufferOperation::OutputPath() { op_.AddLoop(path_); path_.clear(); // Does not change capacity. have_input_start_ = false; have_offset_start_ = false; } // Given a triangle ABC that has just been covered by the sweep edge AB, // updates the winding number of the reference point if necessary. void S2BufferOperation::UpdateRefWinding( const S2Point& a, const S2Point& b, const S2Point& c) { // TODO(ericv): This code could be made much faster by maintaining a // bounding plane that separates the current sweep edge from the reference // point. Whenever the sweep_a_ or sweep_b_ is updated we would just need // to check that the new vertex is still on the opposite side of the // bounding plane (i.e., one dot product). If not, we test the current // triangle using the code below and then compute a new bounding plane. // // Another optimization would be to choose the reference point to be 90 // degrees away from the first input vertex, since then triangle tests would // not be needed unless the input geometry spans more than 90 degrees. This // would involve adding a new flag have_ref_point_ rather than always // choosing the reference point to be S2::Origin(). // // According to profiling these optimizations are not currently worthwhile, // but this is worth revisiting if and when other improvements are made. int sign = s2pred::Sign(a, b, c); if (sign == 0) return; bool inside = S2::AngleContainsVertex(a, b, c) == (sign > 0); S2EdgeCrosser crosser(&b, &ref_point_); inside ^= crosser.EdgeOrVertexCrossing(&a, &b); inside ^= crosser.EdgeOrVertexCrossing(&b, &c); inside ^= crosser.EdgeOrVertexCrossing(&c, &a); if (inside) ref_winding_ += sign; } // Ensures that the output will be the full polygon. void S2BufferOperation::AddFullPolygon() { ref_winding_ += 1; } void S2BufferOperation::AddPoint(const S2Point& point) { // If buffer_radius < 0, points are discarded. if (buffer_sign_ < 0) return; // Buffering by 180 degrees or more always yields the full polygon. // (We don't need to worry about buffering by 180 degrees yielding // a degenerate hole because error_fraction_ is always positive. if (abs_radius_ >= S1ChordAngle::Straight()) { return AddFullPolygon(); } // If buffer_radius == 0, points are converted into degenerate loops. if (buffer_sign_ == 0) { if (!tracker_.AddSpace(&path_, 1)) return; path_.push_back(point); } else { // Since S1ChordAngle can only represent angles between 0 and 180 degrees, // we generate the circle in four 90 degree increments. SetInputVertex(point); S2Point start = S2::Ortho(point); S1ChordAngle angle = S1ChordAngle::Zero(); for (int quadrant = 0; quadrant < 4; ++quadrant) { // Generate 90 degrees of the circular arc. Normalize "rotate_dir" at // each iteration to avoid magnifying normalization errors in "point". S2Point rotate_dir = point.CrossProd(start).Normalize(); for (; angle < S1ChordAngle::Right(); angle += point_step_) { S2Point dir = S2::GetPointOnRay(start, rotate_dir, angle); AddOffsetVertex(S2::GetPointOnRay(point, dir, abs_radius_)); } angle -= S1ChordAngle::Right(); start = rotate_dir; } CloseBufferRegion(); } OutputPath(); } // Returns the edge normal for the given edge AB. The sign is chosen such // that the normal is on the right of AB if buffer_sign_ > 0, and on the left // of AB if buffer_sign_ < 0. inline S2Point S2BufferOperation::GetEdgeAxis(const S2Point& a, const S2Point& b) const { ABSL_DCHECK_NE(buffer_sign_, 0); return buffer_sign_ * S2::RobustCrossProd(b, a).Normalize(); } // Adds a semi-open offset arc around vertex V. The arc proceeds CCW from // "start" to "end" (both of which must be perpendicular to V). void S2BufferOperation::AddVertexArc(const S2Point& v, const S2Point& start, const S2Point& end) { // Make sure that we output at least one point even when span == 0. S2Point rotate_dir = buffer_sign_ * v.CrossProd(start).Normalize(); S1ChordAngle angle, span(start, end); do { S2Point dir = S2::GetPointOnRay(start, rotate_dir, angle); AddOffsetVertex(S2::GetPointOnRay(v, dir, abs_radius_)); } while ((angle += vertex_step_) < span); } // Closes the semi-open arc generated by AddVertexArc(). void S2BufferOperation::CloseVertexArc(const S2Point& v, const S2Point& end) { AddOffsetVertex(S2::GetPointOnRay(v, end, abs_radius_)); } // Adds a semi-open offset arc for the given edge AB. void S2BufferOperation::AddEdgeArc(const S2Point& a, const S2Point& b) { S2Point ab_axis = GetEdgeAxis(a, b); if (edge_step_ == S1ChordAngle::Zero()) { // If the buffer radius is more than 90 degrees, edges do not contribute to // the buffered boundary. Instead we force the offset path to pass // through a vertex located at the edge normal. This is similar to the // case of concave vertices (below) where it is necessary to route the // offset path through the concave vertex to ensure that the winding // numbers in all output regions have the correct sign. AddOffsetVertex(ab_axis); } else { // Make sure that we output at least one point even when span == 0. S2Point rotate_dir = buffer_sign_ * a.CrossProd(ab_axis).Normalize(); S1ChordAngle angle, span(a, b); do { S2Point p = S2::GetPointOnRay(a, rotate_dir, angle); AddOffsetVertex(S2::GetPointOnRay(p, ab_axis, abs_radius_)); } while ((angle += edge_step_) < span); } SetInputVertex(b); } // Closes the semi-open arc generated by AddEdgeArc(). void S2BufferOperation::CloseEdgeArc(const S2Point& a, const S2Point& b) { if (edge_step_ != S1ChordAngle::Zero()) { AddOffsetVertex(S2::GetPointOnRay(b, GetEdgeAxis(a, b), abs_radius_)); } } // Buffers the edge AB and the vertex B. (The vertex C is used to determine // the range of angles that should be buffered at B.) // // TODO(ericv): Let A* denote the possible offset points of A with respect to // the edge AB for buffer radii in the range specified by "radius" and // "error_fraction". Rather than requiring that the path so far terminates at // a point in A*, as you might expect, instead we only require that the path // terminates at a point X such that for any point Y in A*, the edge XY does // not leave the valid buffer zone of the previous edge and vertex. void S2BufferOperation::BufferEdgeAndVertex(const S2Point& a, const S2Point& b, const S2Point& c) { ABSL_DCHECK_NE(a, b); ABSL_DCHECK_NE(b, c); ABSL_DCHECK_NE(buffer_sign_, 0); if (!tracker_.ok()) return; // For left (convex) turns we need to add an offset arc. For right // (concave) turns we connect the end of the current offset path to the // vertex itself and then to the start of the offset path for the next edge. // Note that A == C is considered to represent a convex (left) turn. AddEdgeArc(a, b); if (buffer_sign_ * s2pred::Sign(a, b, c) >= 0) { // The boundary makes a convex turn. If there is no following edge arc // then we need to generate a closed vertex arc. S2Point start = GetEdgeAxis(a, b); S2Point end = GetEdgeAxis(b, c); AddVertexArc(b, start, end); if (edge_step_ == S1ChordAngle::Zero()) CloseVertexArc(b, end); } else { // The boundary makes a concave turn. It is tempting to simply connect // the end of the current offset path to the start of the offset path for // the next edge, however this can create output regions where the winding // number is incorrect. A solution that always works is to terminate the // current offset path and start a new one by connecting the two offset // paths through the input vertex whenever it is concave. We first need // to close the previous semi-open edge arc if necessary. CloseEdgeArc(a, b); AddOffsetVertex(b); // Connect through the input vertex. } } // Given a polyline that starts with the edge AB, adds an end cap (as // specified by end_cap_style() and polyline_side()) for the vertex A. void S2BufferOperation::AddStartCap(const S2Point& a, const S2Point& b) { S2Point axis = GetEdgeAxis(a, b); if (options_.end_cap_style() == EndCapStyle::FLAT) { // One-sided flat end caps require no additional vertices since the // "offset curve" for the opposite side is simply the reversed polyline. if (options_.polyline_side() == PolylineSide::BOTH) { AddOffsetVertex(S2::GetPointOnRay(a, -axis, abs_radius_)); } } else { ABSL_DCHECK(options_.end_cap_style() == EndCapStyle::ROUND); if (options_.polyline_side() == PolylineSide::BOTH) { // The end cap consists of a semicircle. AddVertexArc(a, -axis, axis); } else { // The end cap consists of a quarter circle. Note that for // PolylineSide::LEFT, the polyline direction has been reversed. AddVertexArc(a, axis.CrossProd(a).Normalize(), axis); } } } // Given a polyline that ends with the edge AB, adds an end cap (as specified // by end_cap_style() and polyline_side()) for the vertex B. void S2BufferOperation::AddEndCap(const S2Point& a, const S2Point& b) { S2Point axis = GetEdgeAxis(a, b); if (options_.end_cap_style() == EndCapStyle::FLAT) { CloseEdgeArc(a, b); // Close the previous semi-open edge arc if necessary. } else { ABSL_DCHECK(options_.end_cap_style() == EndCapStyle::ROUND); if (options_.polyline_side() == PolylineSide::BOTH) { // The end cap consists of a semicircle. AddVertexArc(b, axis, -axis); } else { // The end cap consists of a quarter circle. We close the arc since it // will be followed by the reversed polyline vertices. Note that for // PolylineSide::LEFT, the polyline direction has been reversed. S2Point end = b.CrossProd(axis).Normalize(); AddVertexArc(b, axis, end); CloseVertexArc(b, end); } } } // Helper function that buffers the given loop. void S2BufferOperation::BufferLoop(S2PointLoopSpan loop) { // Empty loops always yield an empty path. if (loop.empty() || !tracker_.ok()) return; // Loops with one degenerate edge are treated as points. if (loop.size() == 1) return AddPoint(loop[0]); // Buffering by 180 degrees or more always yields the full polygon. // Buffering by -180 degrees or more always yields the empty polygon. if (abs_radius_ >= S1ChordAngle::Straight()) { if (buffer_sign_ > 0) AddFullPolygon(); return; } // If buffer_radius == 0, the loop is passed through unchanged. if (buffer_sign_ == 0) { if (!tracker_.AddSpace(&path_, loop.size())) return; path_.assign(loop.begin(), loop.end()); } else { SetInputVertex(loop[0]); for (size_t i = 0; i < loop.size(); ++i) { BufferEdgeAndVertex(loop[i], loop[i + 1], loop[i + 2]); } CloseBufferRegion(); } OutputPath(); } void S2BufferOperation::AddPolyline(S2PointSpan polyline) { // Left-sided buffering is supported by reversing the polyline and then // buffering on the right. vector reversed; if (options_.polyline_side() == PolylineSide::LEFT) { reversed.reserve(polyline.size()); std::reverse_copy(polyline.begin(), polyline.end(), std::back_inserter(reversed)); polyline = reversed; } // If buffer_radius < 0, polylines are discarded. if (buffer_sign_ < 0 || !tracker_.ok()) return; // Polylines with 0 or 1 vertices are defined to have no edges. int n = polyline.size(); if (n <= 1) return; // Polylines with one degenerate edge are treated as points. if (n == 2 && polyline[0] == polyline[1]) { return AddPoint(polyline[0]); } // Buffering by 180 degrees or more always yields the full polygon. if (abs_radius_ >= S1ChordAngle::Straight()) { return AddFullPolygon(); } // If buffer_radius == 0, polylines are converted into degenerate loops. if (buffer_sign_ == 0) { if (!tracker_.AddSpace(&path_, 2 * (n - 1))) return; path_.assign(polyline.begin(), polyline.end() - 1); path_.insert(path_.end(), polyline.rbegin(), polyline.rend() - 1); } else { // Otherwise we buffer each side of the polyline separately. SetInputVertex(polyline[0]); AddStartCap(polyline[0], polyline[1]); for (int i = 0; i < n - 2; ++i) { BufferEdgeAndVertex(polyline[i], polyline[i + 1], polyline[i + 2]); } AddEdgeArc(polyline[n - 2], polyline[n - 1]); AddEndCap(polyline[n - 2], polyline[n - 1]); if (options_.polyline_side() == PolylineSide::BOTH) { for (int i = n - 3; i >= 0; --i) { BufferEdgeAndVertex(polyline[i + 2], polyline[i + 1], polyline[i]); } AddEdgeArc(polyline[1], polyline[0]); CloseBufferRegion(); } else { // The other side of the polyline is not buffered. Note that for // PolylineSide::LEFT, the polyline direction has been reversed. if (!tracker_.AddSpace(&path_, n)) return; path_.insert(path_.end(), polyline.rbegin(), polyline.rend()); // Don't call CloseBufferRegion() since the path has already been closed. } } OutputPath(); } void S2BufferOperation::AddLoop(S2PointLoopSpan loop) { if (loop.empty()) return; BufferLoop(loop); // The vertex copying below could be avoided by adding a version of // S2LaxLoopShape that doesn't own its vertices. if (!tracker_.ok()) return; ref_winding_ += s2shapeutil::ContainsBruteForce(S2LaxLoopShape(loop), ref_point_); num_polygon_layers_ += 1; } void S2BufferOperation::BufferShape(const S2Shape& shape) { int dimension = shape.dimension(); int num_chains = shape.num_chains(); for (int c = 0; c < num_chains; ++c) { S2Shape::Chain chain = shape.chain(c); if (chain.length == 0) continue; if (dimension == 0) { AddPoint(shape.edge(c).v0); } else { S2::GetChainVertices(shape, c, &tmp_vertices_); if (dimension == 1) { AddPolyline(S2PointSpan(tmp_vertices_)); } else { BufferLoop(S2PointLoopSpan(tmp_vertices_)); } } } } void S2BufferOperation::AddShape(const S2Shape& shape) { BufferShape(shape); ref_winding_ += s2shapeutil::ContainsBruteForce(shape, ref_point_); num_polygon_layers_ += (shape.dimension() == 2); } void S2BufferOperation::AddShapeIndex(const S2ShapeIndex& index) { int max_dimension = -1; for (const S2Shape* shape : index) { if (shape == nullptr) continue; max_dimension = max(max_dimension, shape->dimension()); BufferShape(*shape); } ref_winding_ += S2ContainsPointQuery(&index).Contains(ref_point_); num_polygon_layers_ += (max_dimension == 2); } bool S2BufferOperation::Build(S2Error* absl_nonnull error) { if (buffer_sign_ < 0 && num_polygon_layers_ > 1) { *error = S2Error::FailedPrecondition( "Negative buffer radius requires at most one polygon layer"); return false; } return op_.Build(ref_point_, ref_winding_, S2WindingOperation::WindingRule::POSITIVE, error); } src/s2/s2buffer_operation.h000066400000000000000000000365711524103652300161550ustar00rootroot00000000000000// Copyright 2020 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #ifndef S2_S2BUFFER_OPERATION_H_ #define S2_S2BUFFER_OPERATION_H_ #include #include #include "absl/base/nullability.h" #include "absl/log/absl_log.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2builder.h" #include "s2/s2error.h" #include "s2/s2memory_tracker.h" #include "s2/s2point.h" #include "s2/s2point_span.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/s2winding_operation.h" // This class provides a way to expand an arbitrary collection of geometry by // a fixed radius (an operation variously known as "buffering", "offsetting", // or "Minkowski sum with a disc"). The output consists of a polygon // (possibly with multiple shells) that contains all points within the given // radius of the original geometry. // // The radius can also be negative, in which case the geometry is contracted. // This causes the boundaries of polygons to shrink or disappear, and removes // all points and polylines. // // The input consists of a sequence of layers. Each layer may consist of any // combination of points, polylines, and polygons, with the restriction that // polygon interiors within each layer may not intersect any other geometry // (including other polygon interiors). The output is the union of the // buffered input layers. Note that only a single layer is allowed if the // buffer radius is negative. // // This class may be used to compute polygon unions by setting the buffer // radius to zero. The union is computed using a single snapping operation. // // Note that if you only want to compute an S2CellId covering of the buffered // geometry, it is much faster to use S2ShapeIndexBufferedRegion instead. // // Keywords: buffer, buffering, expand, expanding, offset, offsetting, // widen, contract, shrink, Minkowski sum class S2BufferOperation { public: // For polylines, specifies whether the end caps should be round or flat. // See Options::set_end_cap_style() below. enum class EndCapStyle : uint8_t { ROUND, FLAT }; // Specifies whether polylines should be buffered only on the left, only on // the right, or on both sides. enum class PolylineSide : uint8_t { LEFT, RIGHT, BOTH }; class Options { public: Options(); // Convenience constructor that calls set_buffer_radius(). explicit Options(S1Angle buffer_radius); // If positive, specifies that all points within the given radius of the // input geometry should be added to the output. If negative, specifies // that all points within the given radius of complement of the input // geometry should be subtracted from the output. If the buffer radius // is zero then the input geometry is passed through to the output layer // after first converting points and polylines into degenerate loops. // // DEFAULT: S1Angle::Zero() S1Angle buffer_radius() const; void set_buffer_radius(S1Angle buffer_radius); // Specifies the allowable error when buffering, expressed as a fraction // of buffer_radius(). The actual buffer distance will be in the range // [(1-f) * r - C, (1 + f) * r + C] where "f" is the error fraction, "r" // is the buffer radius, and "C" is S2BufferOperation::kAbsError. // // Be aware that the number of output edges increases proportionally to // (1 / sqrt(error_fraction)), so setting a small value may increase the // size of the output considerably. // // REQUIRES: error_fraction() >= kMinErrorFraction // REQUIRES: error_fraction() <= 1.0 // // DEFAULT: 0.01 (i.e., maximum error of 1%) static constexpr double kMinErrorFraction = 1e-6; double error_fraction() const; void set_error_fraction(double error_fraction); // Returns the maximum error in the buffered result for the current // buffer_radius(), error_fraction(), and snap_function(). Note that the // error due to buffering consists of both relative errors (those // proportional to the buffer radius) and absolute errors. The maximum // relative error is controlled by error_fraction(), while the maximum // absolute error is about 10 nanometers on the Earth's surface and is // defined internally. The error due to snapping is defined by the // specified snap_function(). S1Angle max_error() const; // Alternatively, error_fraction() may be specified as the number of // polyline segments used to approximate a planar circle. These two // values are related according to the formula // // error_fraction = (1 - cos(theta)) / (1 + cos(theta)) // ~= 0.25 * (theta ** 2) // // where (theta == Pi / circle_segments), i.e. error decreases // quadratically with the number of circle segments. // // REQUIRES: circle_segments() >= 2.0 // REQUIRES: circle_segments() <= kMaxCircleSegments // (about 1570; corresponds to kMinErrorFraction) // // DEFAULT: about 15.76 (corresponding to error_fraction() default value) static constexpr double kMaxCircleSegments = 1570.7968503979573; double circle_segments() const; void set_circle_segments(double circle_segments); // For polylines, specifies whether the end caps should be round or flat. // // Note that with flat end caps, there is no buffering beyond the polyline // endpoints (unlike "square" end caps, which are not implemented). // // DEFAULT: EndCapStyle::ROUND EndCapStyle end_cap_style() const; void set_end_cap_style(EndCapStyle end_cap_style); // Specifies whether polylines should be buffered only on the left, only // on the right, or on both sides. For one-sided buffering please note // the following: // // - EndCapStyle::ROUND yields two quarter-circles, one at each end. // // - To buffer by a different radius on each side of the polyline, you // can use two S2BufferOperations and compute their union. (Note that // round end caps will yield two quarter-circles at each end of the // polyline with different radii.) // // - Polylines consisting of a single degenerate edge are always buffered // identically to points, i.e. this option has no effect. // // - When the polyline turns right by more than 90 degrees, buffering may // or may not extend to the non-buffered side of the polyline. For // example if ABC makes a 170 degree right turn at B, it is unspecified // whether the buffering of AB extends across edge BC and vice versa. // Similarly if ABCD represents two right turns of 90 degrees where AB // and CD are separated by less than the buffer radius, it is // unspecified whether buffering of AB extends across CD and vice versa. // // DEFAULT: PolylineSide::BOTH PolylineSide polyline_side() const; void set_polyline_side(PolylineSide polyline_side); // Specifies the function used for snap rounding the output during the // call to Build(). Note that any errors due to snapping are in addition // to those specified by error_fraction(). // // DEFAULT: s2builderutil::IdentitySnapFunction(S1Angle::Zero()) const S2Builder::SnapFunction& snap_function() const; void set_snap_function(const S2Builder::SnapFunction& snap_function); // Specifies that internal memory usage should be tracked using the given // S2MemoryTracker. If a memory limit is specified and more more memory // than this is required then an error will be returned. Example usage: // // S2MemoryTracker tracker; // tracker.set_limit(500 << 20); // 500 MB // S2BufferOperation::Options options; // options.set_buffer_radius(S1Angle::Degrees(1e-5)); // options.set_memory_tracker(&tracker); // S2BufferOperation op{options}; // ... // S2Error error; // if (!op.Build(&error)) { // if (error.code() == S2Error::RESOURCE_EXHAUSTED) { // ABSL_LOG(ERROR) << error; // Memory limit exceeded // } // } // // CAVEATS: // // - Memory allocated by the output S2Builder layer is not tracked. // // - While memory tracking is reasonably complete and accurate, it does // not account for every last byte. It is intended only for the // purpose of preventing clients from running out of memory. // // DEFAULT: nullptr (memory tracking disabled) S2MemoryTracker* memory_tracker() const; void set_memory_tracker(S2MemoryTracker* tracker); // Options may be assigned and copied. Options(const Options& options); Options& operator=(const Options& options); private: S1Angle buffer_radius_ = S1Angle::Zero(); // double error_fraction_ = 0.01; double error_fraction_ = 0.02; EndCapStyle end_cap_style_ = EndCapStyle::ROUND; PolylineSide polyline_side_ = PolylineSide::BOTH; std::unique_ptr snap_function_; S2MemoryTracker* memory_tracker_ = nullptr; }; // Default constructor; requires Init() to be called. S2BufferOperation(); #ifndef SWIG // Convenience constructor that calls Init(). explicit S2BufferOperation(std::unique_ptr result_layer, const Options& options = Options{}); #endif // Starts a buffer operation that sends the output polygon to the given // S2Builder layer. This method may be called more than once. // // Note that buffering always yields a polygon, even if the input includes // polylines and points. If the buffer radius is zero, points and polylines // will be converted into degenerate polygon loops; if the buffer radius is // negative, points and polylines will be removed. void Init(std::unique_ptr result_layer, const Options& options = Options()); const Options& options() const; // Each call below represents a different input layer. Note that if the // buffer radius is negative, then at most one input layer is allowed // (ignoring any layers that contain only points and polylines). // Adds an input layer containing a single point. void AddPoint(const S2Point& point); // Adds an input layer containing a polyline. Note the following: // // - Polylines with 0 or 1 vertices are considered to be empty. // - A polyline with 2 identical vertices is equivalent to a point. // - Polylines have end caps (see Options::end_cap_style). // - One-sided polyline buffering is supported (see Options::polyline_side). void AddPolyline(S2PointSpan polyline); // Adds an input layer containing a loop. Note the following: // // - A loop with no vertices is empty. // - A loop with 1 vertex is equivalent to a point. // - The interior of the loop is on its left. // - Buffering a self-intersecting loop produces undefined results. void AddLoop(S2PointLoopSpan loop); // Adds an input layer containing the given shape. Shapes are handled as // points, polylines, or polygons according to the rules above. In addition // note the following: // // - Polygons holes may be degenerate (e.g., consisting of a // single vertex or entirely of sibling pairs such as ABCBDB). // - Full polygons are supported. Note that since full polygons do // not have a boundary, they are not affected by buffering. void AddShape(const S2Shape& shape); // Adds an input layer containing all of the shapes in the given index. // // REQUIRES: The interiors of polygons must be disjoint from all other // indexed geometry, including other polygon interiors. // (S2BooleanOperation also requires this.) void AddShapeIndex(const S2ShapeIndex& index); // Computes the union of the buffered input shapes and sends the output // polygon to the S2Builder layer specified in the constructor. Returns // true on success and otherwise sets "error" appropriately. // // Note that if the buffer radius is negative, only a single input layer is // allowed (ignoring any layers that contain only points and polylines). bool Build(S2Error* absl_nonnull error); private: S1Angle GetMaxEdgeSpan(S1Angle radius, S1Angle requested_error) const; void SetInputVertex(const S2Point& new_a); void AddOffsetVertex(const S2Point& new_b); void CloseBufferRegion(); void OutputPath(); void UpdateRefWinding(const S2Point& a, const S2Point& b, const S2Point& c); void AddFullPolygon(); S2Point GetEdgeAxis(const S2Point& a, const S2Point& b) const; void AddVertexArc(const S2Point& v, const S2Point& start, const S2Point& end); void CloseVertexArc(const S2Point& v, const S2Point& end); void AddEdgeArc(const S2Point& a, const S2Point& b); void CloseEdgeArc(const S2Point& a, const S2Point& b); void BufferEdgeAndVertex(const S2Point& a, const S2Point& b, const S2Point& c); void AddStartCap(const S2Point& a, const S2Point& b); void AddEndCap(const S2Point& a, const S2Point& b); void BufferLoop(S2PointLoopSpan loop); void BufferShape(const S2Shape& shape); Options options_; // The number of layers containing two-dimension geometry that have been // added so far. This is used to enforce the requirement that negative // buffer radii allow only a single such layer. int num_polygon_layers_ = 0; // Parameters for buffering vertices and edges. int buffer_sign_; // The sign of buffer_radius (-1, 0, or +1). S1ChordAngle abs_radius_; S1ChordAngle vertex_step_, edge_step_; // We go to extra effort to ensure that points are transformed into regular // polygons. (We don't do this for arcs in general because we would rather // use the allowable error to reduce the complexity of the output rather // than increase its symmetry.) S1ChordAngle point_step_; // Contains the buffered loops that have been accumulated so far. S2WindingOperation op_; // The current offset path. When each path is completed into a loop it is // added to op_ (the S2WindingOperation). std::vector path_; // As buffered loops are added we keep track of the winding number of a // fixed reference point. This is used to derive the winding numbers of // every region in the spherical partition induced by the buffered loops. S2Point ref_point_; // The winding number associated with ref_point_. int ref_winding_; // The endpoints of the current sweep edge. sweep_a_ is a vertex of the // original geometry and sweep_b_ is a vertex of the current offset path. S2Point sweep_a_, sweep_b_; // The starting vertices of the current input loop and offset curve. These // are used to close the buffer region when a loop is completed. S2Point input_start_, offset_start_; bool have_input_start_, have_offset_start_; // Used internally as a temporary to avoid excessive memory allocation. std::vector tmp_vertices_; S2MemoryTracker::Client tracker_; }; #endif // S2_S2BUFFER_OPERATION_H_ src/s2/s2buffer_operation_test.cc000066400000000000000000001000371524103652300173370ustar00rootroot00000000000000// Copyright 2020 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/s2buffer_operation.h" #include #include #include #include #include #include #include #include #include #include #include #include #include #include "absl/base/call_once.h" #include "absl/base/nullability.h" #include "absl/flags/flag.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/log/absl_vlog_is_on.h" #include "absl/log/log_streamer.h" #include "absl/random/random.h" #include "absl/status/status.h" #include "absl/status/statusor.h" #include "absl/strings/str_cat.h" #include "absl/strings/str_format.h" #include "absl/strings/string_view.h" #include "s2/base/malloc_extension.h" #include "s2/mutable_s2shape_index.h" #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2boolean_operation.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_lax_polygon_layer.h" #include "s2/s2builderutil_snap_functions.h" #include "s2/s2cell_id.h" #include "s2/s2closest_edge_query.h" #include "s2/s2closest_edge_query_base.h" #include "s2/s2contains_point_query.h" #include "s2/s2edge_crossings.h" #include "s2/s2edge_distances.h" #include "s2/s2error.h" #include "s2/s2fractal.h" #include "s2/s2lax_loop_shape.h" #include "s2/s2lax_polygon_shape.h" #include "s2/s2lax_polyline_shape.h" #include "s2/s2loop.h" #include "s2/s2memory_tracker.h" #include "s2/s2metrics.h" #include "s2/s2point.h" #include "s2/s2point_span.h" #include "s2/s2point_vector_shape.h" #include "s2/s2pointutil.h" #include "s2/s2polygon.h" #include "s2/s2predicates.h" #include "s2/s2random.h" #include "s2/s2shape.h" #include "s2/s2testing.h" #include "s2/s2text_format.h" using absl::StrCat; using absl::string_view; using std::make_unique; using std::max; using std::string; using std::unique_ptr; using std::vector; using EndCapStyle = S2BufferOperation::EndCapStyle; using PolylineSide = S2BufferOperation::PolylineSide; namespace { // A callback that allows adding input to an S2BufferOperation. This is // convenient for testing the various input methods (AddPoint, AddShape, etc). using InputCallback = std::function; // Convenience function that calls the given lambda expression to add input to // an S2BufferOperation and returns the buffered result. unique_ptr DoBuffer( InputCallback input_callback, const S2BufferOperation::Options& options) { auto output = make_unique(); S2BufferOperation op( make_unique(output.get()), options); input_callback(&op); S2Error error; EXPECT_TRUE(op.Build(&error)) << error; if (ABSL_VLOG_IS_ON(1) && output->num_vertices() < 1000) { std::cerr << "\nS2Polygon: " << s2textformat::ToString(*output) << "\n"; } return output; } // Simpler version that accepts a buffer radius and error fraction. unique_ptr DoBuffer( InputCallback input_callback, S1Angle buffer_radius, double error_fraction) { S2BufferOperation::Options options; options.set_buffer_radius(buffer_radius); options.set_error_fraction(error_fraction); return DoBuffer(std::move(input_callback), options); } // Given a callback that adds empty geometry to the S2BufferOperation, // verifies that the result is empty after buffering. void TestBufferEmpty(InputCallback input) { // Test code paths that involve buffering by negative, zero, and positive // values, and also values where the result is usually empty or full. EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(-200), 0.1)->is_empty()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(-1), 0.1)->is_empty()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(0), 0.1)->is_empty()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(1), 0.1)->is_empty()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(200), 0.1)->is_empty()); } TEST(S2BufferOperation, NoInput) { TestBufferEmpty([](S2BufferOperation* op) {}); } TEST(S2BufferOperation, EmptyPolyline) { // Note that polylines with 1 vertex are defined to have no edges. TestBufferEmpty([](S2BufferOperation* op) { op->AddPolyline(vector{S2Point(1, 0, 0)}); }); } TEST(S2BufferOperation, EmptyLoop) { TestBufferEmpty([](S2BufferOperation* op) { op->AddLoop(vector{}); }); } TEST(S2BufferOperation, EmptyPointShape) { TestBufferEmpty([](S2BufferOperation* op) { op->AddShape(S2PointVectorShape{}); }); } TEST(S2BufferOperation, EmptyPolylineShape) { TestBufferEmpty([](S2BufferOperation* op) { op->AddShape(*s2textformat::MakeLaxPolylineOrDie("")); }); } TEST(S2BufferOperation, EmptyPolygonShape) { TestBufferEmpty([](S2BufferOperation* op) { op->AddShape(*s2textformat::MakeLaxPolygonOrDie("")); }); } TEST(S2BufferOperation, EmptyShapeIndex) { TestBufferEmpty([](S2BufferOperation* op) { op->AddShapeIndex(*s2textformat::MakeIndexOrDie("# #")); }); } TEST(S2BufferOperation, Options) { // Provide test coverage for `options()`. S2BufferOperation::Options options(S1Angle::Radians(1e-12)); S2LaxPolygonShape output; S2BufferOperation op( make_unique(&output), options); EXPECT_EQ(options.buffer_radius(), op.options().buffer_radius()); } TEST(S2BufferOperation, PoorlyNormalizedPoint) { // Verify that debugging assertions are not triggered when an input point is // not unit length (but within the limits guaranteed by S2Point::Normalize). // // The purpose of this test is not to check that the result is correct // (which is done elsewhere), simply that no assertions occur. DoBuffer([](S2BufferOperation* op) { S2Point p(1 - 2 * DBL_EPSILON, 0, 0); // Maximum error allowed. ABSL_CHECK(S2::IsUnitLength(p)); op->AddPoint(p); }, S1Angle::Degrees(1), 0.01); } // Given a callback that adds the full polygon to the S2BufferOperation, // verifies that the result is full after buffering. void TestBufferFull(InputCallback input) { // Test code paths that involve buffering by negative, zero, and positive // values, and also values where the result is usually empty or full. EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(-200), 0.1)->is_full()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(-1), 0.1)->is_full()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(0), 0.1)->is_full()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(1), 0.1)->is_full()); EXPECT_TRUE(DoBuffer(input, S1Angle::Degrees(200), 0.1)->is_full()); } TEST(S2BufferOperation, FullPolygonShape) { TestBufferFull([](S2BufferOperation* op) { op->AddShape(*s2textformat::MakeLaxPolygonOrDie("full")); }); } TEST(S2BufferOperation, FullShapeIndex) { TestBufferFull([](S2BufferOperation* op) { op->AddShapeIndex(*s2textformat::MakeIndexOrDie("# # full")); }); } TEST(S2BufferOperation, PointsAndPolylinesAreRemoved) { // Test that points and polylines are removed with a negative buffer radius. auto output = DoBuffer([](S2BufferOperation* op) { op->AddShapeIndex(*s2textformat::MakeIndexOrDie("0:0 # 2:2, 2:3#")); }, S1Angle::Degrees(-1), 0.1); EXPECT_TRUE(output->is_empty()); } TEST(S2BufferOperation, BufferedPointsAreSymmetric) { // Test that points are buffered into regular polygons. (This is not // guaranteed by the API but makes the output nicer to look at. :) auto output = DoBuffer([](S2BufferOperation* op) { op->AddPoint(S2Point(1, 0, 0)); }, S1Angle::Degrees(5), 0.001234567); // We use the length of the last edge as our reference length. int n = output->num_vertices(); S1Angle edge_len(output->loop_vertex(0, 0), output->loop_vertex(0, n - 1)); for (int i = 1; i < n; ++i) { EXPECT_LE(abs(edge_len - S1Angle(output->loop_vertex(0, i - 1), output->loop_vertex(0, i))), S1Angle::Radians(1e-14)); } } TEST(S2BufferOperation, SetCircleSegments) { // Test that when a point is buffered with a small radius the number of // edges matches options.circle_segments(). (This is not true for large // radii because large circles on the sphere curve less than 360 degrees.) // Using a tiny radius helps to catch rounding problems. S2BufferOperation::Options options(S1Angle::Radians(1e-12)); for (int circle_segments = 3; circle_segments <= 20; ++circle_segments) { options.set_circle_segments(circle_segments); EXPECT_FLOAT_EQ(circle_segments, options.circle_segments()); auto output = DoBuffer([](S2BufferOperation* op) { op->AddPoint(S2Point(1, 0, 0)); }, options); EXPECT_EQ(output->num_vertices(), circle_segments); } } TEST(S2BufferOperation, SetSnapFunction) { // Verify that the snap function is passed through to S2Builder. // We use a buffer radius of zero to make the test simpler. S2BufferOperation::Options options; options.set_snap_function(s2builderutil::IntLatLngSnapFunction(0)); auto output = DoBuffer([](S2BufferOperation* op) { op->AddPoint(s2textformat::MakePointOrDie("0.1:-0.4")); }, options); EXPECT_EQ(output->num_vertices(), 1); EXPECT_EQ(output->loop_vertex(0, 0), s2textformat::MakePointOrDie("0:0")); } TEST(S2BufferOperation, NegativeBufferRadiusMultipleLayers) { // Verify that with a negative buffer radius, at most one polygon layer is // allowed. S2LaxPolygonShape output; S2BufferOperation op( make_unique(&output), S2BufferOperation::Options(S1Angle::Radians(-1))); op.AddLoop(S2PointLoopSpan(s2textformat::ParsePointsOrDie("0:0, 0:1, 1:0"))); op.AddShapeIndex(*s2textformat::MakeIndexOrDie("# # 2:2, 2:3, 3:2")); S2Error error; EXPECT_FALSE(op.Build(&error)); EXPECT_EQ(error.code(), S2Error::FAILED_PRECONDITION); } // If buffer_radius > max_error, tests that "output" contains "input". // If buffer_radius < -max_error tests that "input" contains "output". // Otherwise does nothing. void TestContainment(const MutableS2ShapeIndex& input, const MutableS2ShapeIndex& output, S1Angle buffer_radius, S1Angle max_error) { S2BooleanOperation::Options options; options.set_polygon_model(S2BooleanOperation::PolygonModel::CLOSED); options.set_polyline_model(S2BooleanOperation::PolylineModel::CLOSED); if (buffer_radius > max_error) { // For positive buffer radii, the output should contain the input. EXPECT_TRUE(S2BooleanOperation::Contains(output, input, options)); } else if (buffer_radius < -max_error) { // For negative buffer radii, the input should contain the output. EXPECT_TRUE(S2BooleanOperation::Contains(input, output, options)); } } // Tests that the minimum distance from the boundary of "output" to the // boundary of "input" is at least "min_dist" using exact predicates. void TestMinimumDistance(const MutableS2ShapeIndex& input, const MutableS2ShapeIndex& output, S1ChordAngle min_dist) { if (min_dist == S1ChordAngle::Zero()) return; // We do one query to find the edges of "input" that might be too close to // "output", then for each such edge we do another query to find the edges // of "output" that might be too close to it. Then we check the distance // between each edge pair (A, B) using exact predicates. // We make the distance limit big enough to find all edges whose true // distance might be less than "min_dist". S2ClosestEdgeQuery::Options query_options; query_options.set_include_interiors(false); query_options.set_max_distance( min_dist.PlusError(S2::GetUpdateMinDistanceMaxError(min_dist))); S2ClosestEdgeQuery in_query(&input, query_options); S2ClosestEdgeQuery::ShapeIndexTarget out_target(&output); out_target.set_include_interiors(false); S2ClosestEdgeQuery out_query(&output, query_options); for (const auto& in_result : in_query.FindClosestEdges(&out_target)) { auto a = input.shape(in_result.shape_id())->edge(in_result.edge_id()); S2ClosestEdgeQuery::EdgeTarget in_target(a.v0, a.v1); for (const auto& out_result : out_query.FindClosestEdges(&in_target)) { auto b = output.shape(out_result.shape_id())->edge(out_result.edge_id()); ASSERT_GE( s2pred::CompareEdgePairDistance(a.v0, a.v1, b.v0, b.v1, min_dist), 0); } } } // Tests that the Hausdorff distance from the boundary of "output" to the // boundary of "input" is at most (1 + error_fraction) * buffer_radius. The // implementation approximates this by measuring the distance at a set of // points along the boundary of "output". void TestHausdorffDistance(const MutableS2ShapeIndex& input, const MutableS2ShapeIndex& output, S1ChordAngle max_dist) { S2ClosestEdgeQuery::Options query_options; query_options.set_include_interiors(false); query_options.set_max_distance( max_dist.PlusError(S2::GetUpdateMinDistanceMaxError(max_dist))); S2ClosestEdgeQuery in_query(&input, query_options); for (const S2Shape* out_shape : output) { for (int i = 0; i < out_shape->num_edges(); ++i) { S2Shape::Edge e = out_shape->edge(i); // Measure the distance at 5 points along the edge. for (double t = 0; t <= 1.0; t += 0.25) { S2Point b = S2::Interpolate(e.v0, e.v1, t); S2ClosestEdgeQuery::PointTarget out_target(b); // We check the distance bound using exact predicates. for (const auto& in_result : in_query.FindClosestEdges(&out_target)) { auto a = input.shape(in_result.shape_id())->edge(in_result.edge_id()); ASSERT_LE(s2pred::CompareEdgeDistance(b, a.v0, a.v1, max_dist), 0); } } } } } // Buffers the given input with the given buffer_radius and error_fraction and // verifies that the output is correct. void TestBuffer(const MutableS2ShapeIndex& input, S1Angle buffer_radius, double error_fraction) { ABSL_LOG(INFO) << "TestBuffer: " << s2textformat::ToString(input) << " buffer_radius: " << buffer_radius.radians() << " error_fraction: " << error_fraction; // Ideally we would verify the correctness of buffering as follows. Suppose // that B = Buffer(A, r) and let ~X denote the complement of region X. Then // if r > 0, we would verify: // // 1a. Minimum distance between ~B and A >= r_min // 1b. Directed Hausdorff distance from B to A <= r_max // // Buffering A by r < 0 is equivalent to buffering ~A by |r|, so instead we // would verify the following (where r_min and r_max are based on |r|): // // 2a. Minimum distance between B and ~A >= r_min // 2b. Directed Hausdorff distance from ~B to ~A <= r_max // // Conditions 1a and 2a can be implemented as follows: // // 1a*: B.Contains(A) && minimum distance between @B and @A >= r_min // 2a*: A.Contains(B) && minimum distance between @B and @A >= r_min // // Note that if r_min <= 0 then there is nothing to be tested, since the // containment condition may not hold. (Note that even when the specified // buffer radius is zero, edges can move slightly when crossing edges are // split during the snapping step.) The correct approach would be to test // instead that the directed Hausdorff distance from A to ~B is at most // -r_min, but Hausdorff distance is not yet implemented. // // Similarly, conditions 1b and 2b need to be approximated because Hausdorff // distance is not yet implemented. We do this by measuring the distance at // a set of points on the boundary of B: // // 1b*: Minimum distance from P to @A <= r_max for a set of points P on @B // 2b*: Minimum distance from P to @A <= r_max for a set of points P on @B // // This is not perfect (e.g., it won't detect cases where an entire boundary // loop of B is missing, such as returning a disc in the place of an // annulus) but it is sufficient to detect many types of errors. S2BufferOperation::Options options; options.set_buffer_radius(buffer_radius); options.set_error_fraction(error_fraction); MutableS2ShapeIndex output; output.Add(DoBuffer( [&input](S2BufferOperation* op) { op->AddShapeIndex(input); }, options)); SCOPED_TRACE(absl::StrFormat( "\nradius = %.17g, error_fraction = %.17g\ninput = %s\noutput = %s", buffer_radius.radians(), error_fraction, s2textformat::ToString(input), s2textformat::ToString(output))); // Check the 1a*/1b* condition above. S1Angle max_error = options.max_error(); TestContainment(input, output, buffer_radius, max_error); S1ChordAngle min_dist(max(S1Angle::Zero(), abs(buffer_radius) - max_error)); TestMinimumDistance(input, output, min_dist); // Check the 2a*/2b* condition (i.e., directed Hausdorff distance). S1ChordAngle max_dist(abs(buffer_radius) + max_error); TestHausdorffDistance(input, output, max_dist); } // Convenience function that takes an S2ShapeIndex in s2textformat format. void TestBuffer(string_view index_str, S1Angle buffer_radius, double error_fraction) { TestBuffer(*s2textformat::MakeIndexOrDie(index_str), buffer_radius, error_fraction); } // Convenience function that tests buffering using +/- the given radius. void TestSignedBuffer(string_view index_str, S1Angle buffer_radius, double error_fraction) { TestBuffer(index_str, buffer_radius, error_fraction); TestBuffer(index_str, -buffer_radius, error_fraction); } TEST(S2BufferOperation, PointShell) { TestSignedBuffer("# # 0:0", S1Angle::Radians(M_PI_2), 0.01); } TEST(S2BufferOperation, SiblingPairShell) { TestSignedBuffer("# # 0:0, 0:5", S1Angle::Radians(M_PI_2), 0.01); } TEST(S2BufferOperation, SiblingPairHole) { TestSignedBuffer("# # 0:0, 0:10, 7:7; 3:4, 3:6", S1Angle::Degrees(1), 0.01); } TEST(S2BufferOperation, Square) { TestSignedBuffer("# # -3:-3, -3:3, 3:3, 3:-3", S1Angle::Degrees(1), 0.01); TestSignedBuffer("# # -3:-3, -3:3, 3:3, 3:-3", S1Angle::Degrees(170), 1e-4); } TEST(S2BufferOperation, HollowSquare) { TestSignedBuffer("# # -3:-3, -3:3, 3:3, 3:-3; 2:2, -2:2, -2:-2, 2:-2", S1Angle::Degrees(1), 0.01); } TEST(S2BufferOperation, ZigZagLoop) { TestSignedBuffer("# # 0:0, 0:7, 5:3, 5:10, 6:10, 6:1, 1:5, 1:0", S1Angle::Degrees(0.2), 0.01); } TEST(S2BufferOperation, Fractals) { absl::BitGen bitgen( S2Testing::MakeTaggedSeedSeq("FRACTALS", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); for (double dimension : {1.02, 1.8}) { S2Fractal fractal(bitgen); fractal.SetLevelForApproxMaxEdges(3 * 64); fractal.set_fractal_dimension(dimension); auto loop = fractal.MakeLoop(S2::GetFrame(S2Point(1, 0, 0)), S1Angle::Degrees(10)); MutableS2ShapeIndex input; input.Add(make_unique(loop.get())); TestBuffer(input, S1Angle::Degrees(0.4), 0.01); } } TEST(S2BufferOperation, S2Curve) { // Tests buffering the S2 curve by an amount that yields the full polygon. constexpr int kLevel = 2; // Number of input edges == 6 * (4 ** kLevel) vector points; for (S2CellId id = S2CellId::Begin(kLevel); id != S2CellId::End(kLevel); id = id.next()) { points.push_back(id.ToPoint()); } // Buffering by this amount or more is guaranteed to yield the full polygon. // (Note that the bound is not tight for S2CellIds at low levels.) S1Angle full_radius = S1Angle::Radians(0.5 * S2::kMaxDiag.GetValue(kLevel)); EXPECT_TRUE(DoBuffer([&points](S2BufferOperation* op) { op->AddShape(S2LaxClosedPolylineShape(points)); }, full_radius, 0.1)->is_full()); } // Tests buffering the given S2ShapeIndex with a variety of radii and error // fractions. This method is intended to be used with relatively simple // shapes since calling it is quite expensive. void TestRadiiAndErrorFractions(string_view index_str) { // Try the full range of radii with a representative error fraction. constexpr double kFrac = 0.01; vector kTestRadiiRadians = { 0, 1e-300, 1e-15, 2e-15, 3e-15, 1e-5, 0.01, 0.1, 1.0, (1 - kFrac) * M_PI_2, M_PI_2 - 1e-15, M_PI_2, M_PI_2 + 1e-15, (1 - kFrac) * M_PI, M_PI - 1e-6, M_PI, 1e300 }; for (double radius : kTestRadiiRadians) { TestSignedBuffer(index_str, S1Angle::Radians(radius), kFrac); } // Now try the full range of error fractions with a few selected radii. vector kTestErrorFractions = {S2BufferOperation::Options::kMinErrorFraction, 0.001, 0.01, 0.1, 1.0}; for (double error_fraction : kTestErrorFractions) { TestBuffer(index_str, S1Angle::Radians(-1e-6), error_fraction); TestBuffer(index_str, S1Angle::Radians(1e-14), error_fraction); TestBuffer(index_str, S1Angle::Radians(1e-2), error_fraction); TestBuffer(index_str, S1Angle::Radians(M_PI - 1e-3), error_fraction); } } // Test buffering simple shapes with a wide range of different buffer radii // and error fractions. TEST(S2BufferOperation, RadiiAndErrorFractionCoverageSinglePoint) { TestRadiiAndErrorFractions("1:1 # #"); } TEST(S2BufferOperation, RadiiAndErrorFractionCoverageZigZagPolyline) { TestRadiiAndErrorFractions("# 0:0, 0:30, 30:30, 30:60 #"); } TEST(S2BufferOperation, RadiiAndErrorFractionCoverageTriangleWithHole) { // A triangular polygon with a triangular hole. (The hole is clockwise.) TestRadiiAndErrorFractions("# # 0:0, 0:100, 70:50; 10:20, 50:50, 10:80"); } TEST(S2BufferOperation, RadiiAndErrorFractionCoverageTriangleTwoLongEdges) { // A triangle with one very short and two very long edges. TestRadiiAndErrorFractions("# # 0:0, 0:179.99999999999, 1e-300:0"); } class TestBufferPolyline { public: TestBufferPolyline(string_view input_str, const S2BufferOperation::Options& options); private: static constexpr double kArcLo = 0.001; static constexpr double kArcHi = 0.999; static constexpr int kArcSamples = 7; S2Point GetEdgeAxis(const S2Point& a, const S2Point& b) { return S2::RobustCrossProd(a, b).Normalize(); } bool PointBufferingUncertain(const S2Point& p, bool expect_contained) { // The only case where a point might be excluded from the buffered output is // if it is on the unbuffered side of the polyline. if (expect_contained && two_sided_) return false; int n = polyline_.size(); for (int i = 0; i < n - 1; ++i) { const S2Point& a = polyline_[i]; const S2Point& b = polyline_[i + 1]; if (!two_sided_) { // Ignore points on the buffered side if expect_contained is true, // and on the unbuffered side if expect_contained is false. if ((s2pred::Sign(a, b, p) < 0) == expect_contained) continue; } // TODO(ericv): Depending on how the erasing optimization is implemented, // it might be possible to add "&& expect_contained" to the test below. if (round_) { if (S2::IsDistanceLess(p, a, b, max_dist_)) return true; } else { if (S2::IsInteriorDistanceLess(p, a, b, max_dist_)) return true; if (i > 0 && S1ChordAngle(p, a) < max_dist_) return true; if (i == n - 2 && S1ChordAngle(p, b) < max_dist_) return true; } } return false; } void TestPoint(const S2Point& p, const S2Point& dir, bool expect_contained) { S2Point x = S2::GetPointOnRay( p, dir, expect_contained ? buffer_radius_ - max_error_ : max_error_); if (!PointBufferingUncertain(x, expect_contained)) { EXPECT_EQ(S2ContainsPointQuery(&output_).Contains(x), expect_contained); } } void TestVertexArc(const S2Point& p, const S2Point& start, const S2Point& end, bool expect_contained) { for (double t = kArcLo; t < 1; t += (kArcHi - kArcLo) / kArcSamples) { S2Point dir = S2::Interpolate(start, end, t); TestPoint(p, dir, expect_contained); } } void TestEdgeArc(const S2Point& ba_axis, const S2Point& a, const S2Point& b, bool expect_contained) { for (double t = kArcLo; t < 1; t += (kArcHi - kArcLo) / kArcSamples) { S2Point p = S2::Interpolate(a, b, t); TestPoint(p, ba_axis, expect_contained); } } void TestEdgeAndVertex(const S2Point& a, const S2Point& b, const S2Point& c, bool expect_contained) { S2Point ba_axis = GetEdgeAxis(b, a); S2Point cb_axis = GetEdgeAxis(c, b); TestEdgeArc(ba_axis, a, b, expect_contained); TestVertexArc(b, ba_axis, cb_axis, expect_contained); } vector polyline_; MutableS2ShapeIndex output_; S1Angle buffer_radius_, max_error_; S1ChordAngle min_dist_, max_dist_; bool round_, two_sided_; }; // Tests buffering a polyline with the given options. This method is intended // only for testing Options::EndCapStyle and Options::PolylineSide; if these // options have their default values then TestBuffer() should be used // instead. Similarly TestBuffer should be used to test negative buffer radii // and polylines with 0 or 1 vertices. TestBufferPolyline::TestBufferPolyline( string_view input_str, const S2BufferOperation::Options& options) : polyline_(s2textformat::ParsePointsOrDie(input_str)), buffer_radius_(options.buffer_radius()), max_error_(options.max_error()), min_dist_(max(S1Angle::Zero(), buffer_radius_ - max_error_)), max_dist_(buffer_radius_ + max_error_), round_(options.end_cap_style() == EndCapStyle::ROUND), two_sided_(options.polyline_side() == PolylineSide::BOTH) { ABSL_DCHECK_GE(polyline_.size(), 2); ABSL_DCHECK(buffer_radius_ > S1Angle::Zero()); MutableS2ShapeIndex input; input.Add(s2textformat::MakeLaxPolylineOrDie(input_str)); output_.Add(DoBuffer( [&input](S2BufferOperation* op) { op->AddShapeIndex(input); }, options)); // Even with one-sided buffering and flat end caps the Hausdorff distance // criterion should still be true. (This checks that the buffered result // is never further than (buffer_radius + max_error) from the input.) TestHausdorffDistance(input, output_, max_dist_); // However the minimum distance criterion is different; it only applies to // the portions of the boundary that are buffered using the given radius. // We check this approximately by walking along the polyline and checking // that (1) on portions of the polyline that should be buffered, the output // contains the offset point at distance (buffer_radius - max_error) and (2) // on portions of the polyline that should not be buffered, the output does // not contain the offset point at distance max_error. The tricky part is // that both of these conditions have exceptions: (1) may not hold if the // test point is closest to the non-buffered side of the polyline (see the // last caveat in the documentation for Options::polyline_side), and (2) // may not hold if the test point is within (buffer_radius + max_error) of // the buffered side of any portion of the polyline. if (min_dist_ == S1ChordAngle::Zero()) return; // Left-sided buffering is tested by reversing the polyline and then testing // whether it has been buffered correctly on the right. if (options.polyline_side() == PolylineSide::LEFT) { std::reverse(polyline_.begin(), polyline_.end()); } int n = polyline_.size(); S2Point start0 = polyline_[0], start1 = polyline_[1]; S2Point start_begin = GetEdgeAxis(start0, start1); S2Point start_mid = start0.CrossProd(start_begin); TestVertexArc(start0, start_begin, start_mid, round_ && two_sided_); TestVertexArc(start0, start_mid, -start_begin, round_); for (int i = 0; i < n - 2; ++i) { TestEdgeAndVertex(polyline_[i], polyline_[i + 1], polyline_[i + 2], true); } S2Point end0 = polyline_[n - 1], end1 = polyline_[n - 2]; S2Point end_begin = GetEdgeAxis(end0, end1); S2Point end_mid = end0.CrossProd(end_begin); TestEdgeArc(end_begin, end1, end0, true); TestVertexArc(end0, end_begin, end_mid, round_); TestVertexArc(end0, end_mid, -end_begin, round_ && two_sided_); for (int i = n - 3; i >= 0; --i) { TestEdgeAndVertex(polyline_[i + 2], polyline_[i + 1], polyline_[i], two_sided_); } TestEdgeArc(start_begin, start1, start0, two_sided_); } TEST(S2BufferOperation, ZigZagPolyline) { S2BufferOperation::Options options(S1Angle::Degrees(1)); for (PolylineSide polyline_side : { PolylineSide::LEFT, PolylineSide::RIGHT, PolylineSide::BOTH}) { for (EndCapStyle end_cap_style : { EndCapStyle::ROUND, EndCapStyle::FLAT}) { SCOPED_TRACE(absl::StrFormat( "two_sided = %d, round = %d", polyline_side == PolylineSide::BOTH, end_cap_style == EndCapStyle::ROUND)); options.set_polyline_side(polyline_side); options.set_end_cap_style(end_cap_style); TestBufferPolyline("0:0, 0:7, 5:3, 5:10", options); // NOLINT TestBufferPolyline("10:0, 0:0, 5:1", options); // NOLINT } } } void BM_BufferPoints(benchmark::State& state) { const string seed_str = StrCat("BUFFER_POINTS", absl::GetFlag(FLAGS_s2_random_seed)); std::seed_seq seed(seed_str.begin(), seed_str.end()); std::mt19937_64 bitgen(seed); int num_points = state.range(0); S1Angle buffer_radius = S2Testing::MetersToAngle(100); for (auto _ : state) { S2LaxPolygonShape output; S2BufferOperation op(make_unique(&output), S2BufferOperation::Options{buffer_radius}); for (int i = 0; i < num_points; ++i) { op.AddPoint(s2random::Point(bitgen)); } S2Error error; ABSL_CHECK(op.Build(&error)) << error; } } BENCHMARK(BM_BufferPoints)->Arg(1)->Arg(10)->Arg(1000); void BenchmarkBufferLoop(benchmark::State& state, S2PointLoopSpan loop, S1Angle buffer_radius) { for (auto _ : state) { S2LaxPolygonShape output; S2BufferOperation op(make_unique(&output), S2BufferOperation::Options{buffer_radius}); op.AddLoop(loop); S2Error error; ABSL_CHECK(op.Build(&error)) << error; } } void BM_BufferConvexLoop(benchmark::State& state) { auto loop = S2Testing::MakeRegularPoints( S2Point(1, 0, 0), S2Testing::MetersToAngle(1000), state.range(0)); S1Angle buffer_radius = S2Testing::MetersToAngle(state.range(1)); BenchmarkBufferLoop(state, loop, buffer_radius); } BENCHMARK(BM_BufferConvexLoop) ->ArgPair(10, 10)->ArgPair(1000, 10)->ArgPair(1000, 1000); void BM_BufferConcaveLoop(benchmark::State& state) { auto loop = S2Testing::MakeRegularPoints( S2Point(1, 0, 0), S2Testing::MetersToAngle(1000), state.range(0)); std::reverse(loop.begin(), loop.end()); S1Angle buffer_radius = S2Testing::MetersToAngle(state.range(1)); BenchmarkBufferLoop(state, loop, buffer_radius); } BENCHMARK(BM_BufferConcaveLoop) ->ArgPair(10, 10)->ArgPair(1000, 10)->ArgPair(1000, 100); void BenchmarkBufferFractal( benchmark::State& state, int num_edges, S1Angle nominal_radius, double dimension, S1Angle buffer_radius) { const string seed_str = StrCat("BUFFER_FRACTAL", absl::GetFlag(FLAGS_s2_random_seed)); std::seed_seq seed(seed_str.begin(), seed_str.end()); std::mt19937_64 bitgen(seed); S2Fractal fractal(bitgen); fractal.SetLevelForApproxMaxEdges(num_edges); fractal.set_fractal_dimension(dimension); auto loop = fractal.MakeLoop(s2random::Frame(bitgen), nominal_radius); S2PointLoopSpan loop_span(&loop->vertex(0), loop->num_vertices()); BenchmarkBufferLoop(state, loop_span, buffer_radius); } void BM_BufferLoDimFractal(benchmark::State& state) { BenchmarkBufferFractal( state, state.range(0), S1Angle::Degrees(10), 1.05, S1Angle::Degrees(0.1)); } BENCHMARK(BM_BufferLoDimFractal) ->Arg(3 * 16)->Arg(3 * 1024); void BM_BufferHiDimFractal(benchmark::State& state) { BenchmarkBufferFractal( state, state.range(0), S1Angle::Degrees(10), 1.5, S1Angle::Degrees(0.1)); } BENCHMARK(BM_BufferHiDimFractal) ->Arg(3 * 16)->Arg(3 * 1024); } // namespace src/s2/s2builder.cc000066400000000000000000003000311524103652300143710ustar00rootroot00000000000000// Copyright 2016 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) // // The algorithm is based on the idea of choosing a set of sites and computing // their "limited radius Voronoi diagram", which is obtained by intersecting // each Voronoi region with a disc of fixed radius (the "snap radius") // centered around the corresponding site. // // For each input edge, we then determine the sequence of Voronoi regions // crossed by that edge, and snap the edge to the corresponding sequence of // sites. (In other words, each input edge is replaced by an edge chain.) // // The sites are chosen by starting with the set of input vertices, optionally // snapping them to discrete point set (such as S2CellId centers or lat/lng E7 // coordinates), and then choosing a subset such that no two sites are closer // than the given "snap_radius". Note that the sites do not need to be spaced // regularly -- their positions are completely arbitrary. // // Rather than computing the full limited radius Voronoi diagram, instead we // compute on demand the sequence of Voronoi regions intersected by each edge. // We do this by first finding all the sites that are within "snap_radius" of // the edge, sorting them by distance from the edge origin, and then using an // incremental algorithm. // // We implement the minimum edge-vertex separation property by snapping all // the input edges and checking whether any site (the "site to avoid") would // then be too close to the edge. If so we add another site (the "separation // site") along the input edge, positioned so that the new snapped edge is // guaranteed to be far enough away from the site to avoid. We then find all // the input edges that are within "snap_radius" of the new site, and resnap // those edges. (It is very rare that we need to add a separation site, even // when sites are densely spaced.) // // Idempotency is implemented by explicitly checking whether the input // geometry already meets the output criteria. This is not as sophisticated // as Stable Snap Rounding (Hershberger); I have worked out the details and it // is possible to adapt those ideas here, but it would make the implementation // significantly more complex. // // The only way that different output layers interact is in the choice of // Voronoi sites: // // - Vertices from all layers contribute to the initial selection of sites. // // - Edges in any layer that pass too close to a site can cause new sites to // be added (which affects snapping in all layers). // // - Simplification can be thought of as removing sites. A site can be // removed only if the snapped edges stay within the error bounds of the // corresponding input edges in all layers. // // Otherwise all layers are processed independently. For example, sibling // edge pairs can only cancel each other within a single layer (if desired). #include "s2/s2builder.h" #include #include #include #include #include #include #include #include #include #include "absl/base/nullability.h" #include "absl/cleanup/cleanup.h" #include "absl/container/btree_map.h" #include "absl/container/flat_hash_set.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/strings/str_format.h" #include "absl/types/span.h" #include "s2/base/casts.h" #include "s2/base/log_severity.h" #include "s2/id_set_lexicon.h" #include "s2/mutable_s2shape_index.h" #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2builder_graph.h" #include "s2/s2builder_layer.h" #include "s2/s2builderutil_snap_functions.h" #include "s2/s2cell_id.h" #include "s2/s2closest_edge_query.h" #include "s2/s2closest_edge_query_base.h" #include "s2/s2closest_point_query.h" #include "s2/s2closest_point_query_base.h" #include "s2/s2crossing_edge_query.h" #include "s2/s2edge_crossings.h" #include "s2/s2edge_distances.h" #include "s2/s2error.h" #include "s2/s2loop.h" #include "s2/s2point.h" #include "s2/s2point_index.h" #include "s2/s2point_span.h" #include "s2/s2polygon.h" #include "s2/s2polyline.h" #include "s2/s2polyline_simplifier.h" #include "s2/s2predicates.h" #include "s2/s2shape.h" #include "s2/s2shapeutil_shape_edge.h" #include "s2/s2shapeutil_visit_crossing_edge_pairs.h" #include "s2/s2text_format.h" #include "s2/util/gtl/compact_array.h" using absl::flat_hash_set; using gtl::compact_array; using std::make_unique; using std::max; using std::pair; using std::unique_ptr; using std::vector; S2Builder::Options::Options() : snap_function_( make_unique(S1Angle::Zero())) { } S2Builder::Options::Options(const SnapFunction& snap_function) : snap_function_(snap_function.Clone()) { } S2Builder::Options::Options(const Options& options) : snap_function_(options.snap_function_->Clone()), split_crossing_edges_(options.split_crossing_edges_), intersection_tolerance_(options.intersection_tolerance_), simplify_edge_chains_(options.simplify_edge_chains_), idempotent_(options.idempotent_), memory_tracker_(options.memory_tracker_) { } S2Builder::Options& S2Builder::Options::operator=(const Options& options) { snap_function_ = options.snap_function_->Clone(); split_crossing_edges_ = options.split_crossing_edges_; intersection_tolerance_ = options.intersection_tolerance_; simplify_edge_chains_ = options.simplify_edge_chains_; idempotent_ = options.idempotent_; memory_tracker_ = options.memory_tracker_; return *this; } S1Angle S2Builder::Options::edge_snap_radius() const { return snap_function().snap_radius() + intersection_tolerance(); } S1Angle S2Builder::Options::max_edge_deviation() const { // We want max_edge_deviation() to be large enough compared to snap_radius() // such that edge splitting is rare. // // Using spherical trigonometry, if the endpoints of an edge of length L // move by at most a distance R, the center of the edge moves by at most // asin(sin(R) / cos(L / 2)). Thus the (max_edge_deviation / snap_radius) // ratio increases with both the snap radius R and the edge length L. // // We arbitrarily limit the edge deviation to be at most 10% more than the // snap radius. With the maximum allowed snap radius of 70 degrees, this // means that edges up to 30.6 degrees long are never split. For smaller // snap radii, edges up to 49 degrees long are never split. (Edges of any // length are not split unless their endpoints move far enough so that the // actual edge deviation exceeds the limit; in practice, splitting is rare // even with long edges.) Note that it is always possible to split edges // when max_edge_deviation() is exceeded; see MaybeAddExtraSites(). ABSL_DCHECK_LE(snap_function().snap_radius(), SnapFunction::kMaxSnapRadius()); const double kMaxEdgeDeviationRatio = 1.1; return kMaxEdgeDeviationRatio * edge_snap_radius(); } bool operator==(const S2Builder::GraphOptions& x, const S2Builder::GraphOptions& y) { return (x.edge_type() == y.edge_type() && x.degenerate_edges() == y.degenerate_edges() && x.duplicate_edges() == y.duplicate_edges() && x.sibling_pairs() == y.sibling_pairs() && x.allow_vertex_filtering() == y.allow_vertex_filtering()); } // Helper functions for computing error bounds: static S1ChordAngle RoundUp(S1Angle a) { S1ChordAngle ca(a); return ca.PlusError(ca.GetS1AngleConstructorMaxError()); } static S1ChordAngle AddPointToPointError(S1ChordAngle ca) { return ca.PlusError(ca.GetS2PointConstructorMaxError()); } static S1ChordAngle AddPointToEdgeError(S1ChordAngle ca) { return ca.PlusError(S2::GetUpdateMinDistanceMaxError(ca)); } S2Builder::S2Builder() = default; S2Builder::S2Builder(const Options& options) { Init(options); } void S2Builder::Init(const Options& options) { options_ = options; const SnapFunction& snap_function = options.snap_function(); S1Angle snap_radius = snap_function.snap_radius(); ABSL_DCHECK_LE(snap_radius, SnapFunction::kMaxSnapRadius()); // Convert the snap radius to an S1ChordAngle. This is the "true snap // radius" used when evaluating exact predicates (s2predicates.h). site_snap_radius_ca_ = S1ChordAngle(snap_radius); // When intersection_tolerance() is non-zero we need to use a larger snap // radius for edges than for vertices to ensure that both edges are snapped // to the edge intersection location. This is because the computed // intersection point is not exact; it may be up to intersection_tolerance() // away from its true position. The computed intersection point might then // be snapped to some other vertex up to snap_radius away. So to ensure // that both edges are snapped to a common vertex, we need to increase the // snap radius for edges to at least the sum of these two values (calculated // conservatively). S1Angle edge_snap_radius = options.edge_snap_radius(); edge_snap_radius_ca_ = RoundUp(edge_snap_radius); snapping_requested_ = (edge_snap_radius > S1Angle::Zero()); // Compute the maximum distance that a vertex can be separated from an // edge while still affecting how that edge is snapped. max_edge_deviation_ = options.max_edge_deviation(); edge_site_query_radius_ca_ = S1ChordAngle( max_edge_deviation_ + snap_function.min_edge_vertex_separation()); // Compute the maximum edge length such that even if both endpoints move by // the maximum distance allowed (i.e., edge_snap_radius), the center of the // edge will still move by less than max_edge_deviation(). This saves us a // lot of work since then we don't need to check the actual deviation. if (!snapping_requested_) { min_edge_length_to_split_ca_ = S1ChordAngle::Infinity(); } else { // This value varies between 30 and 50 degrees depending on the snap radius. min_edge_length_to_split_ca_ = S1ChordAngle::Radians( 2 * acos(sin(edge_snap_radius) / sin(max_edge_deviation_))); } // In rare cases we may need to explicitly check that the input topology is // preserved, i.e. that edges do not cross vertices when snapped. This is // only necessary (1) for vertices added using ForceVertex(), and (2) when the // snap radius is smaller than intersection_tolerance() (which is typically // either zero or S2::kIntersectionError, about 9e-16 radians). This // condition arises because when a geodesic edge is snapped, the edge center // can move further than its endpoints. This can cause an edge to pass on the // wrong side of an input vertex. (Note that this could not happen in a // planar version of this algorithm.) Usually we don't need to consider this // possibility explicitly, because if the snapped edge passes on the wrong // side of a vertex then it is also closer than min_edge_vertex_separation() // to that vertex, which will cause a separation site to be added. // // If the condition below is true then we need to check all sites (i.e., // snapped input vertices) for topology changes. However this is almost never // the case because // // max_edge_deviation() == 1.1 * edge_snap_radius() // and min_edge_vertex_separation() >= 0.219 * snap_radius() // // for all currently implemented snap functions. The condition below is // only true when intersection_tolerance() is non-zero (which causes // edge_snap_radius() to exceed snap_radius() by S2::kIntersectionError) and // snap_radius() is very small (at most S2::kIntersectionError / 1.19). check_all_site_crossings_ = (options.max_edge_deviation() > options.edge_snap_radius() + snap_function.min_edge_vertex_separation()); if (options.intersection_tolerance() <= S1Angle::Zero()) { ABSL_DCHECK(!check_all_site_crossings_); } // To implement idempotency, we check whether the input geometry could // possibly be the output of a previous S2Builder invocation. This involves // testing whether any site/site or edge/site pairs are too close together. // This is done using exact predicates, which require converting the minimum // separation values to an S1ChordAngle. min_site_separation_ = snap_function.min_vertex_separation(); min_site_separation_ca_ = S1ChordAngle(min_site_separation_); min_edge_site_separation_ca_ = S1ChordAngle(snap_function.min_edge_vertex_separation()); // This is an upper bound on the distance computed by S2ClosestPointQuery // where the true distance might be less than min_edge_site_separation_ca_. min_edge_site_separation_ca_limit_ = AddPointToEdgeError(min_edge_site_separation_ca_); // Compute the maximum possible distance between two sites whose Voronoi // regions touch. (The maximum radius of each Voronoi region is // edge_snap_radius_.) Then increase this bound to account for errors. max_adjacent_site_separation_ca_ = AddPointToPointError(RoundUp(2 * edge_snap_radius)); // Finally, we also precompute sin^2(edge_snap_radius), which is simply the // squared distance between a vertex and an edge measured perpendicular to // the plane containing the edge, and increase this value by the maximum // error in the calculation to compare this distance against the bound. double d = sin(edge_snap_radius); edge_snap_radius_sin2_ = d * d; edge_snap_radius_sin2_ += ((9.5 * d + 2.5 + 2 * sqrt(3)) * d + 9 * DBL_EPSILON) * DBL_EPSILON; // Initialize the current label set. label_set_id_ = label_set_lexicon_.EmptySetId(); label_set_modified_ = false; // If snapping was requested, we try to determine whether the input geometry // already meets the output requirements. This is necessary for // idempotency, and can also save work. If we discover any reason that the // input geometry needs to be modified, snapping_needed_ is set to true. snapping_needed_ = false; tracker_.Init(options.memory_tracker()); } void S2Builder::clear_labels() { label_set_.clear(); label_set_modified_ = true; } void S2Builder::push_label(Label label) { ABSL_DCHECK_GE(label, 0); label_set_.push_back(label); label_set_modified_ = true; } void S2Builder::pop_label() { label_set_.pop_back(); label_set_modified_ = true; } void S2Builder::set_label(Label label) { ABSL_DCHECK_GE(label, 0); label_set_.resize(1); label_set_[0] = label; label_set_modified_ = true; } bool S2Builder::IsFullPolygonUnspecified(const S2Builder::Graph& g, S2Error* absl_nonnull error) { *error = S2Error(S2Error::BUILDER_IS_FULL_PREDICATE_NOT_SPECIFIED, "A degenerate polygon was found, but no predicate was specified " "to determine whether the polygon is empty or full. Call " "S2Builder::AddIsFullPolygonPredicate() to fix this problem."); return false; // Assumes the polygon is empty. } S2Builder::IsFullPolygonPredicate S2Builder::IsFullPolygon(bool is_full) { return [is_full](const S2Builder::Graph& g, S2Error* absl_nonnull error) { return is_full; }; } void S2Builder::StartLayer(unique_ptr layer) { layer_options_.push_back(layer->graph_options()); layer_begins_.push_back(input_edges_.size()); layer_is_full_polygon_predicates_.push_back(IsFullPolygon(false)); layers_.push_back(std::move(layer)); } // Input vertices are stored in a vector, with some removal of duplicates. // Edges are represented as (VertexId, VertexId) pairs. All edges are stored // in a single vector; each layer corresponds to a contiguous range. S2Builder::InputVertexId S2Builder::AddVertex(const S2Point& v) { // Remove duplicate vertices that follow the pattern AB, BC, CD. If we want // to do anything more sophisticated, either use a ValueLexicon, or sort the // vertices once they have all been added, remove duplicates, and update the // edges. if (input_vertices_.empty() || v != input_vertices_.back()) { if (!tracker_.AddSpace(&input_vertices_, 1)) return -1; input_vertices_.push_back(v); } return input_vertices_.size() - 1; } void S2Builder::AddIntersection(const S2Point& vertex) { // It is an error to call this method without first setting // intersection_tolerance() to a non-zero value. ABSL_DCHECK_GT(options_.intersection_tolerance(), S1Angle::Zero()); // Calling this method also overrides the idempotent() option. snapping_needed_ = true; AddVertex(vertex); } void S2Builder::AddEdge(const S2Point& v0, const S2Point& v1) { ABSL_DCHECK(!layers_.empty()) << "Call StartLayer before adding any edges"; if (v0 == v1 && (layer_options_.back().degenerate_edges() == GraphOptions::DegenerateEdges::DISCARD)) { return; } InputVertexId j0 = AddVertex(v0); InputVertexId j1 = AddVertex(v1); if (!tracker_.AddSpace(&input_edges_, 1)) return; input_edges_.push_back(InputEdge(j0, j1)); // If there are any labels, then attach them to this input edge. if (label_set_modified_) { if (label_set_ids_.empty()) { // Populate the missing entries with empty label sets. label_set_ids_.assign(input_edges_.size() - 1, label_set_id_); } label_set_id_ = label_set_lexicon_.Add(label_set_); label_set_ids_.push_back(label_set_id_); label_set_modified_ = false; } else if (!label_set_ids_.empty()) { label_set_ids_.push_back(label_set_id_); } } void S2Builder::AddPolyline(S2PointSpan polyline) { for (size_t i = 1; i < polyline.size(); ++i) { AddEdge(polyline[i - 1], polyline[i]); } } void S2Builder::AddPolyline(const S2Polyline& polyline) { const int n = polyline.num_vertices(); for (int i = 1; i < n; ++i) { AddEdge(polyline.vertex(i - 1), polyline.vertex(i)); } } void S2Builder::AddLoop(S2PointLoopSpan loop) { for (size_t i = 0; i < loop.size(); ++i) { AddEdge(loop[i], loop[i + 1]); } } void S2Builder::AddLoop(const S2Loop& loop) { // Ignore loops with a single vertex, as they do not have a boundary. if (loop.is_empty_or_full()) return; // For loops that represent holes, we add the edge from vertex n-1 to vertex // n-2 first. This is because these edges will be assembled into a // clockwise loop, which will eventually be normalized in S2Polygon by // calling S2Loop::Invert(). S2Loop::Invert() reverses the order of the // vertices, so to end up with the original vertex order (0, 1, ..., n-1) we // need to build a clockwise loop with vertex order (n-1, n-2, ..., 0). // This is done by adding the edge (n-1, n-2) first, and then ensuring that // Build() assembles loops starting from edges in the order they were added. const int n = loop.num_vertices(); for (int i = 0; i < n; ++i) { AddEdge(loop.oriented_vertex(i), loop.oriented_vertex(i + 1)); } } void S2Builder::AddPolygon(const S2Polygon& polygon) { for (int i = 0; i < polygon.num_loops(); ++i) { AddLoop(*polygon.loop(i)); } } void S2Builder::AddShape(const S2Shape& shape) { for (int e = 0, n = shape.num_edges(); e < n; ++e) { S2Shape::Edge edge = shape.edge(e); AddEdge(edge.v0, edge.v1); } } void S2Builder::AddIsFullPolygonPredicate(IsFullPolygonPredicate predicate) { layer_is_full_polygon_predicates_.back() = std::move(predicate); } void S2Builder::ForceVertex(const S2Point& vertex) { if (!tracker_.AddSpace(&sites_, 1)) return; sites_.push_back(vertex); } // An S2Shape used to represent the entire collection of S2Builder input edges. // Vertices are specified as indices into a vertex vector to save space. namespace { class VertexIdEdgeVectorShape final : public S2Shape { public: // Requires that "edges" is constant for the lifetime of this object. VertexIdEdgeVectorShape(const vector>& edges, const vector& vertices) : edges_(edges), vertices_(vertices) {} const S2Point& vertex0(int e) const { return vertex(edges_[e].first); } const S2Point& vertex1(int e) const { return vertex(edges_[e].second); } // S2Shape interface: int num_edges() const override { return edges_.size(); } Edge edge(int e) const override { return Edge(vertices_[edges_[e].first], vertices_[edges_[e].second]); } int dimension() const override { return 1; } ReferencePoint GetReferencePoint() const override { return ReferencePoint::Contained(false); } int num_chains() const override { return edges_.size(); } Chain chain(int i) const override { return Chain(i, 1); } Edge chain_edge(int i, int j) const override { return edge(i); } ChainPosition chain_position(int e) const override { return ChainPosition(e, 0); } private: const S2Point& vertex(int i) const { return vertices_[i]; } const vector>& edges_; const vector& vertices_; }; } // namespace bool S2Builder::Build(S2Error* absl_nonnull error) { error_ = error; *error_ = S2Error::Ok(); // Mark the end of the last layer. layer_begins_.push_back(input_edges_.size()); // See the algorithm overview at the top of this file. if (snapping_requested_ && !options_.idempotent()) { snapping_needed_ = true; } ChooseSites(); BuildLayers(); Reset(); if (!tracker_.ok()) *error_ = tracker_.error(); return error_->ok(); } void S2Builder::Reset() { // Note that these calls do not change vector capacities. input_vertices_.clear(); input_edges_.clear(); layers_.clear(); layer_options_.clear(); layer_begins_.clear(); layer_is_full_polygon_predicates_.clear(); label_set_ids_.clear(); label_set_lexicon_.Clear(); label_set_.clear(); label_set_modified_ = false; sites_.clear(); edge_sites_.clear(); snapping_needed_ = false; } void S2Builder::ChooseSites() { if (!tracker_.ok() || input_vertices_.empty()) return; // Note that although we always create an S2ShapeIndex, often it is not // actually built (because this happens lazily). Therefore we only test // its memory usage at the places where it is used. MutableS2ShapeIndex input_edge_index; input_edge_index.set_memory_tracker(tracker_.tracker()); input_edge_index.Add(make_unique(input_edges_, input_vertices_)); if (options_.split_crossing_edges()) { AddEdgeCrossings(input_edge_index); } if (snapping_requested_) { S2PointIndex site_index; auto _ = absl::MakeCleanup([&]() { tracker_.DoneSiteIndex(site_index); }); AddForcedSites(&site_index); ChooseInitialSites(&site_index); if (!tracker_.FixSiteIndexTally(site_index)) return; CollectSiteEdges(site_index); } if (snapping_needed_) { AddExtraSites(input_edge_index); } else { ChooseAllVerticesAsSites(); } } void S2Builder::ChooseAllVerticesAsSites() { // Sort the input vertices, discard duplicates, and use the result as the // list of sites. (We sort in the same order used by ChooseInitialSites() // to avoid inconsistencies in tests.) We also copy the result back to // input_vertices_ and update the input edges to use the new vertex // numbering (so that InputVertexId == SiteId). This simplifies the // implementation of SnapEdge() for this case. sites_.clear(); if (!tracker_.AddSpaceExact(&sites_, input_vertices_.size())) return; const int64_t kTempPerVertex = sizeof(InputVertexKey) + sizeof(InputVertexId); if (!tracker_.TallyTemp(input_vertices_.size() * kTempPerVertex)) return; vector sorted = SortInputVertices(); vector vmap(input_vertices_.size()); for (size_t in = 0; in < sorted.size();) { const S2Point& site = input_vertices_[sorted[in].second]; vmap[sorted[in].second] = sites_.size(); while (++in < sorted.size() && input_vertices_[sorted[in].second] == site) { vmap[sorted[in].second] = sites_.size(); } sites_.push_back(site); } input_vertices_ = sites_; // Does not change allocated size. for (InputEdge& e : input_edges_) { e.first = vmap[e.first]; e.second = vmap[e.second]; } } vector S2Builder::SortInputVertices() { // Sort all the input vertices in the order that we wish to consider them as // candidate Voronoi sites. ChooseAllVerticesAsSites() requires duplicate // points be adjacent in the sorted output for deduplication. Otherwise, any // sort order will produce correct output, so we have complete flexibility in // choosing the sort key. We could even leave them unsorted, although this // would have the disadvantage that changing the order of the input edges // could cause S2Builder to snap to a different set of Voronoi sites. // // We have chosen to sort them primarily by S2CellId since this improves the // performance of many S2Builder phases (due to better spatial locality). It // also allows the possibility of replacing the current S2PointIndex approach // with a more efficient recursive divide-and-conquer algorithm. Ties are // broken by comparing the S2Point values of vertices lexicographically. // // However, sorting by leaf S2CellId alone has two small disadvantages in // the case where the candidate sites are densely spaced relative to the // snap radius (e.g., when using the IdentitySnapFunction, or when snapping // to E6/E7 near the poles, or snapping to S2CellId/E6/E7 using a snap // radius larger than the minimum value required): // // - First, it tends to bias the Voronoi site locations towards points that // are earlier on the S2CellId Hilbert curve. For example, suppose that // there are two parallel rows of input vertices on opposite sides of the // edge between two large S2Cells, and the rows are separated by less // than the snap radius. Then only vertices from the cell with the // smaller S2CellId are selected, because they are considered first and // prevent us from selecting the sites from the other cell (because they // are closer than "snap_radius" to an existing site). // // - Second, it tends to choose more Voronoi sites than necessary, because // at each step we choose the first site along the Hilbert curve that is // at least "snap_radius" away from all previously selected sites. This // tends to yield sites whose "coverage discs" overlap quite a bit, // whereas it would be better to cover all the input vertices with a // smaller set of coverage discs that don't overlap as much. (This is // the "geometric set cover problem", which is NP-hard.) // // It is not worth going to much trouble to fix these problems, because they // really aren't that important (and don't affect the guarantees made by the // algorithm), but here are a couple of heuristics that might help: // // 1. Sort the input vertices by S2CellId at a coarse level (down to cells // that are O(snap_radius) in size), and then sort by a fingerprint of the // S2Point coordinates (i.e., quasi-randomly). This would retain most of // the advantages of S2CellId sorting, but makes it more likely that we will // select sites that are further apart. // // 2. Rather than choosing the first uncovered input vertex and snapping it // to obtain the next Voronoi site, instead look ahead through following // candidates in S2CellId order and choose the furthest candidate whose // snapped location covers all previous uncovered input vertices. // // TODO(ericv): Experiment with these approaches. vector keys; keys.reserve(input_vertices_.size()); for (InputVertexId i = 0; static_cast(i) < input_vertices_.size(); ++i) { keys.push_back(InputVertexKey(S2CellId(input_vertices_[i]), i)); } std::sort(keys.begin(), keys.end(), [this](const InputVertexKey& a, const InputVertexKey& b) { if (a.first < b.first) return true; if (b.first < a.first) return false; if (input_vertices_[a.second] < input_vertices_[b.second]) return true; if (input_vertices_[b.second] < input_vertices_[a.second]) return false; return a.second < b.second; // Tie-break to ensure deterministic result. }); return keys; } // Check all edge pairs for crossings, and add the corresponding intersection // points to input_vertices_. (The intersection points will be snapped and // merged with the other vertices during site selection.) void S2Builder::AddEdgeCrossings(const MutableS2ShapeIndex& input_edge_index) { input_edge_index.ForceBuild(); if (!tracker_.ok()) return; // We need to build a list of intersections and add them afterwards so that // we don't reallocate vertices_ during the VisitCrossings() call. vector new_vertices; auto _ = absl::MakeCleanup([&]() { tracker_.Untally(new_vertices); }); s2shapeutil::VisitCrossingEdgePairs( input_edge_index, s2shapeutil::CrossingType::INTERIOR, [this, &new_vertices](const s2shapeutil::ShapeEdge& a, const s2shapeutil::ShapeEdge& b, bool) { if (!tracker_.AddSpace(&new_vertices, 1)) return false; new_vertices.push_back( S2::GetIntersection(a.v0(), a.v1(), b.v0(), b.v1())); return true; }); if (new_vertices.empty()) return; snapping_needed_ = true; if (!tracker_.AddSpaceExact(&input_vertices_, new_vertices.size())) return; input_vertices_.insert(input_vertices_.end(), new_vertices.begin(), new_vertices.end()); } void S2Builder::AddForcedSites(S2PointIndex* site_index) { // Sort the forced sites and remove duplicates. std::sort(sites_.begin(), sites_.end()); sites_.erase(std::unique(sites_.begin(), sites_.end()), sites_.end()); // Add the forced sites to the index. for (SiteId id = 0; static_cast(id) < sites_.size(); ++id) { if (!tracker_.TallyIndexedSite()) return; site_index->Add(sites_[id], id); } num_forced_sites_ = sites_.size(); } void S2Builder::ChooseInitialSites(S2PointIndex* site_index) { // Prepare to find all points whose distance is <= min_site_separation_ca_. S2ClosestPointQueryOptions options; options.set_conservative_max_distance(min_site_separation_ca_); S2ClosestPointQuery site_query(site_index, options); vector::Result> results; // Apply the snap_function() to each input vertex, then check whether any // existing site is closer than min_vertex_separation(). If not, then add a // new site. // // NOTE(ericv): There are actually two reasonable algorithms, which we call // "snap first" (the one above) and "snap last". The latter checks for each // input vertex whether any existing site is closer than snap_radius(), and // only then applies the snap_function() and adds a new site. "Snap last" // can yield slightly fewer sites in some cases, but it is also more // expensive and can produce surprising results. For example, if you snap // the polyline "0:0, 0:0.7" using IntLatLngSnapFunction(0), the result is // "0:0, 0:0" rather than the expected "0:0, 0:1", because the snap radius // is approximately sqrt(2) degrees and therefore it is legal to snap both // input points to "0:0". "Snap first" produces "0:0, 0:1" as expected. // // Track the memory used by SortInputVertices() before calling it. if (!tracker_.Tally(input_vertices_.size() * sizeof(InputVertexKey))) return; vector sorted_keys = SortInputVertices(); auto _ = absl::MakeCleanup([&]() { tracker_.Untally(sorted_keys); }); for (const InputVertexKey& key : sorted_keys) { const S2Point& vertex = input_vertices_[key.second]; S2Point site = SnapSite(vertex); // If any vertex moves when snapped, the output cannot be idempotent. snapping_needed_ = snapping_needed_ || site != vertex; bool add_site = true; if (site_snap_radius_ca_ == S1ChordAngle::Zero()) { add_site = sites_.empty() || site != sites_.back(); } else { // FindClosestPoints() measures distances conservatively, so we need to // recheck the distances using exact predicates. // // NOTE(ericv): When the snap radius is large compared to the average // vertex spacing, we could possibly avoid the call the FindClosestPoints // by checking whether sites_.back() is close enough. S2ClosestPointQueryPointTarget target(site); site_query.FindClosestPoints(&target, &results); for (const auto& result : results) { if (s2pred::CompareDistance(site, result.point(), min_site_separation_ca_) <= 0) { add_site = false; // This pair of sites is too close. If the sites are distinct, then // the output cannot be idempotent. snapping_needed_ = snapping_needed_ || site != result.point(); } } } if (add_site) { if (!tracker_.TallyIndexedSite()) return; site_index->Add(site, sites_.size()); if (!tracker_.AddSpace(&sites_, 1)) return; sites_.push_back(site); site_query.ReInit(); } } } S2Point S2Builder::SnapSite(const S2Point& point) const { if (!snapping_requested_) return point; S2Point site = options_.snap_function().SnapPoint(point); S1ChordAngle dist_moved(site, point); if (dist_moved > site_snap_radius_ca_) { *error_ = S2Error( S2Error::BUILDER_SNAP_RADIUS_TOO_SMALL, absl::StrFormat("Snap function moved vertex (%.15g, %.15g, %.15g) " "by %.15g, which is more than the specified snap " "radius of %.15g", point.x(), point.y(), point.z(), dist_moved.ToAngle().radians(), site_snap_radius_ca_.ToAngle().radians())); } return site; } // For each edge, find all sites within edge_site_query_radius_ca_ and // store them in edge_sites_. Also, to implement idempotency this method also // checks whether the input vertices and edges may already satisfy the output // criteria. If any problems are found then snapping_needed_ is set to true. void S2Builder::CollectSiteEdges(const S2PointIndex& site_index) { // Find all points whose distance is <= edge_site_query_radius_ca_. // // Memory used by S2ClosestPointQuery is not tracked, but it is temporary, // typically insignificant, and does not affect the high water mark. S2ClosestPointQueryOptions options; options.set_conservative_max_distance(edge_site_query_radius_ca_); S2ClosestPointQuery site_query(&site_index, options); vector::Result> results; if (!tracker_.AddSpaceExact(&edge_sites_, input_edges_.size())) return; edge_sites_.resize(input_edges_.size()); // Construct all elements. for (InputEdgeId e = 0; static_cast(e) < input_edges_.size(); ++e) { const InputEdge& edge = input_edges_[e]; const S2Point& v0 = input_vertices_[edge.first]; const S2Point& v1 = input_vertices_[edge.second]; S2ClosestPointQueryEdgeTarget target(v0, v1); site_query.FindClosestPoints(&target, &results); auto* sites = &edge_sites_[e]; sites->reserve(results.size()); for (const auto& result : results) { sites->push_back(result.data()); if (!snapping_needed_ && result.distance() < min_edge_site_separation_ca_limit_ && result.point() != v0 && result.point() != v1 && s2pred::CompareEdgeDistance(result.point(), v0, v1, min_edge_site_separation_ca_) < 0) { snapping_needed_ = true; } } SortSitesByDistance(v0, sites); if (!tracker_.TallyEdgeSites(*sites)) return; } } // Sorts the sites in increasing order of distance to X. void S2Builder::SortSitesByDistance(const S2Point& x, compact_array* sites) const { std::sort(sites->begin(), sites->end(), [&x, this](SiteId i, SiteId j) { if (i == j) return false; int diff = s2pred::CompareDistances(x, sites_[i], sites_[j]); if (diff < 0) return true; if (diff > 0) return false; return i < j; // Tie-break to ensure deterministic result. }); } // Like the above, but inserts "new_site_id" into an already-sorted list. void S2Builder::InsertSiteByDistance(SiteId new_site_id, const S2Point& x, compact_array* sites) { if (!tracker_.ReserveEdgeSite(sites)) return; sites->insert(std::lower_bound( sites->begin(), sites->end(), new_site_id, [&x, this](SiteId i, SiteId j) { return s2pred::CompareDistances(x, sites_[i], sites_[j]) < 0; }), new_site_id); } // There are two situations where we need to add extra Voronoi sites in order to // ensure that the snapped edges meet the output requirements: // // (1) If a snapped edge deviates from its input edge by more than // max_edge_deviation(), we add a new site on the input edge near the // middle of the snapped edge. This causes the snapped edge to split // into two pieces, so that it follows the input edge more closely. // // (2) If a snapped edge is closer than min_edge_vertex_separation() to any // nearby site (the "site to avoid") or passes on the wrong side of it // relative to the input edge, then we add a new site (the "separation // site") along the input edge near the site to avoid. This causes the // snapped edge to follow the input edge more closely, so that it is // guaranteed to pass on the correct side of the site to avoid with a // separation of at least the required distance. // // We check these conditions by snapping all the input edges to a chain of // Voronoi sites and then testing each edge in the chain. If a site needs to // be added, we mark all nearby edges for re-snapping. void S2Builder::AddExtraSites(const MutableS2ShapeIndex& input_edge_index) { // Note that we could save some work in AddSnappedEdges() by saving the // snapped edge chains in a vector, but currently this is not worthwhile // since SnapEdge() accounts for less than 5% of the runtime. // Using 18 buckets is equivalent to `reserve(16)`, which was the // `expected_max_elements` used by the old `dense_hash_set` version. // This will actually get us 31 buckets since it gets rounded up. // We could experiment with different values here. flat_hash_set edges_to_resnap(/*bucket_count=*/18); vector chain; // Temporary storage. int num_edges_after_snapping = 0; // CheckEdge() defines the body of the loops below. const auto CheckEdge = [&](InputEdgeId e) -> bool { if (!tracker_.ok()) return false; SnapEdge(e, &chain); edges_to_resnap.erase(e); num_edges_after_snapping += chain.size(); MaybeAddExtraSites(e, chain, input_edge_index, &edges_to_resnap); return true; }; // The first pass is different because we snap every edge. In the following // passes we only snap edges that are near the extra sites that were added. ABSL_VLOG(1) << "Before pass 0: sites=" << sites_.size(); for (InputEdgeId e = 0; static_cast(e) < input_edges_.size(); ++e) { if (!CheckEdge(e)) return; } ABSL_VLOG(1) << "Pass 0: edges snapped=" << input_edges_.size() << ", output edges=" << num_edges_after_snapping << ", sites=" << sites_.size(); for (int num_passes = 1; !edges_to_resnap.empty(); ++num_passes) { auto edges_to_snap = edges_to_resnap; edges_to_resnap.clear(); num_edges_after_snapping = 0; for (InputEdgeId e : edges_to_snap) { if (!CheckEdge(e)) return; } ABSL_VLOG(1) << "Pass " << num_passes << ": edges snapped=" << edges_to_snap.size() << ", output edges=" << num_edges_after_snapping << ", sites=" << sites_.size(); } } void S2Builder::MaybeAddExtraSites( InputEdgeId edge_id, absl::Span chain, const MutableS2ShapeIndex& input_edge_index, flat_hash_set* edges_to_resnap) { // If the memory tracker has a periodic callback function, tally an amount // of memory proportional to the work being done so that the caller has an // opportunity to cancel the operation if necessary. if (!tracker_.TallyTemp(chain.size() * sizeof(chain[0]))) return; // If the input includes NaN vertices, snapping can produce an empty chain. if (chain.empty()) return; // The snapped edge chain is always a subsequence of the nearby sites // (edge_sites_), so we walk through the two arrays in parallel looking for // sites that weren't snapped. These are the "sites to avoid". We also keep // track of the current snapped edge, since it is the only edge that can be // too close or pass on the wrong side of a site to avoid. Vertices beyond // the chain endpoints in either direction can be ignored because only the // interiors of chain edges can be too close to a site to avoid. const InputEdge& edge = input_edges_[edge_id]; const S2Point& a0 = input_vertices_[edge.first]; const S2Point& a1 = input_vertices_[edge.second]; const auto& nearby_sites = edge_sites_[edge_id]; for (size_t i = 0, j = 0; j < nearby_sites.size(); ++j) { SiteId id = nearby_sites[j]; if (id == chain[i]) { // This site is a vertex of the snapped edge chain. if (++i == chain.size()) { break; // Sites beyond the end of the snapped chain can be ignored. } // Check whether this snapped edge deviates too far from its original // position. If so, we split the edge by adding an extra site. const S2Point& v0 = sites_[chain[i - 1]]; const S2Point& v1 = sites_[chain[i]]; if (S1ChordAngle(v0, v1) < min_edge_length_to_split_ca_) continue; if (!S2::IsEdgeBNearEdgeA(a0, a1, v0, v1, max_edge_deviation_)) { // Add a new site on the input edge, positioned so that it splits the // snapped edge into two approximately equal pieces. Then we find all // the edges near the new site (including this one) and add them to // the snap queue. // // Note that with large snap radii, it is possible that the snapped // edge wraps around the sphere the "wrong way". To handle this we // find the preferred split location by projecting both endpoints onto // the input edge and taking their midpoint. S2Point mid = (S2::Project(v0, a0, a1) + S2::Project(v1, a0, a1)).Normalize(); S2Point new_site = GetSeparationSite(mid, v0, v1, edge_id); AddExtraSite(new_site, input_edge_index, edges_to_resnap); // In the case where the edge wrapped around the sphere the "wrong // way", it is not safe to continue checking this edge. It will be // marked for resnapping and we will come back to it in the next pass. return; } } else { // This site is near the input edge but is not part of the snapped chain. if (i == 0) { continue; // Sites before the start of the chain can be ignored. } // We need to ensure that non-forced sites are separated by at least // min_edge_vertex_separation() from the snapped chain. This happens // automatically as part of the algorithm except where there are portions // of the input edge that are not within edge_snap_radius() of any site. // These portions of the original edge are called "coverage gaps". // Therefore if we find that a site to avoid that is too close to the // snapped edge chain, we can fix the problem by adding a new site (the // "separation site") in the corresponding coverage gap located as closely // as possible to the site to avoid. This technique is is guaranteed to // produce the required minimum separation, and the entire process of // adding separation sites is guaranteed to terminate. const S2Point& site_to_avoid = sites_[id]; const S2Point& v0 = sites_[chain[i - 1]]; const S2Point& v1 = sites_[chain[i]]; bool add_separation_site = false; if (!is_forced(id) && min_edge_site_separation_ca_ > S1ChordAngle::Zero() && s2pred::CompareEdgeDistance( site_to_avoid, v0, v1, min_edge_site_separation_ca_) < 0) { add_separation_site = true; } // Similarly, we also add a separation site whenever a snapped edge passes // on the wrong side of a site to avoid. Normally we don't need to worry // about this, since if an edge passes on the wrong side of a nearby site // then it is also too close to it. However if the snap radius is very // small and intersection_tolerance() is non-zero then we need to check // this condition explicitly (see the "check_all_site_crossings_" flag for // details). We also need to check this condition explicitly for forced // vertices. Again, we can solve this problem by adding a "separation // site" in the corresponding coverage gap located as closely as possible // to the site to avoid. // // It is possible to show that when all points are projected onto the // great circle through (a0, a1), no improper crossing occurs unless the // the site to avoid is located between a0 and a1, and also between v0 // and v1. TODO(ericv): Verify whether all these checks are necessary. if (!add_separation_site && (is_forced(id) || check_all_site_crossings_) && (s2pred::Sign(a0, a1, site_to_avoid) != s2pred::Sign(v0, v1, site_to_avoid))&& s2pred::CompareEdgeDirections(a0, a1, a0, site_to_avoid) > 0 && s2pred::CompareEdgeDirections(a0, a1, site_to_avoid, a1) > 0 && s2pred::CompareEdgeDirections(a0, a1, v0, site_to_avoid) > 0 && s2pred::CompareEdgeDirections(a0, a1, site_to_avoid, v1) > 0) { add_separation_site = true; } if (add_separation_site) { // We add a new site (the separation site) in the coverage gap along the // input edge, located as closely as possible to the site to avoid. // Then we find all the edges near the new site (including this one) and // add them to the snap queue. S2Point new_site = GetSeparationSite(site_to_avoid, v0, v1, edge_id); ABSL_DCHECK_NE(site_to_avoid, new_site); AddExtraSite(new_site, input_edge_index, edges_to_resnap); // Skip the remaining sites near this chain edge, and then continue // scanning this chain. Note that this is safe even though the call // to AddExtraSite() above added a new site to "nearby_sites". for (; nearby_sites[j + 1] != chain[i]; ++j) {} } } } } // Adds a new site, then updates "edge_sites_" for all edges near the new site // and adds them to "edges_to_resnap" for resnapping. void S2Builder::AddExtraSite(const S2Point& new_site, const MutableS2ShapeIndex& input_edge_index, flat_hash_set* edges_to_resnap) { if (!sites_.empty()) ABSL_DCHECK_NE(new_site, sites_.back()); if (!tracker_.AddSpace(&sites_, 1)) return; SiteId new_site_id = sites_.size(); sites_.push_back(new_site); // Find all edges whose distance is <= edge_site_query_radius_ca_. S2ClosestEdgeQuery::Options options; options.set_conservative_max_distance(edge_site_query_radius_ca_); options.set_include_interiors(false); if (!input_edge_index.is_fresh()) input_edge_index.ForceBuild(); if (!tracker_.ok()) return; // Memory used by S2ClosestEdgeQuery is not tracked, but it is temporary, // typically insignificant, and does not affect the high water mark. S2ClosestEdgeQuery query(&input_edge_index, options); S2ClosestEdgeQuery::PointTarget target(new_site); for (const auto& result : query.FindClosestEdges(&target)) { InputEdgeId e = result.edge_id(); const S2Point& v0 = input_vertices_[input_edges_[e].first]; InsertSiteByDistance(new_site_id, v0, &edge_sites_[e]); edges_to_resnap->insert(e); } } S2Point S2Builder::GetSeparationSite(const S2Point& site_to_avoid, const S2Point& v0, const S2Point& v1, InputEdgeId input_edge_id) const { // Define the "coverage disc" of a site S to be the disc centered at S with // radius "snap_radius". Similarly, define the "coverage interval" of S for // an edge XY to be the intersection of XY with the coverage disc of S. The // SnapFunction implementations guarantee that the only way that a snapped // edge can be closer than min_edge_vertex_separation() to a non-snapped // site (i.e., site_to_avoid) if is there is a gap in the coverage of XY // near this site. We can fix this problem simply by adding a new site to // fill this gap, located as closely as possible to the site to avoid. // // To calculate the coverage gap, we look at the two snapped sites on // either side of site_to_avoid, and find the endpoints of their coverage // intervals. The we place a new site in the gap, located as closely as // possible to the site to avoid. Note that the new site may move when it // is snapped by the snap_function, but it is guaranteed not to move by // more than snap_radius and therefore its coverage interval will still // intersect the gap. const InputEdge& edge = input_edges_[input_edge_id]; const S2Point& x = input_vertices_[edge.first]; const S2Point& y = input_vertices_[edge.second]; Vector3_d xy_dir = y - x; S2Point n = S2::RobustCrossProd(x, y); S2Point new_site = S2::Project(site_to_avoid, x, y, n); S2Point gap_min = GetCoverageEndpoint(v0, n); S2Point gap_max = GetCoverageEndpoint(v1, -n); if ((new_site - gap_min).DotProd(xy_dir) < 0) { new_site = gap_min; } else if ((gap_max - new_site).DotProd(xy_dir) < 0) { new_site = gap_max; } new_site = SnapSite(new_site); ABSL_DCHECK_NE(v0, new_site); ABSL_DCHECK_NE(v1, new_site); return new_site; } // Given a site P and an edge XY with normal N, intersect XY with the disc of // radius snap_radius() around P, and return the intersection point that is // further along the edge XY toward Y. S2Point S2Builder::GetCoverageEndpoint(const S2Point& p, const S2Point& n) const { // Consider the plane perpendicular to P that cuts off a spherical cap of // radius snap_radius(). This plane intersects the plane through the edge // XY (perpendicular to N) along a line, and that line intersects the unit // sphere at two points Q and R, and we want to return the point R that is // further along the edge XY toward Y. // // Let M be the midpoint of QR. This is the point along QR that is closest // to P. We can now express R as the sum of two perpendicular vectors OM // and MR in the plane XY. Vector MR is in the direction N x P, while // vector OM is in the direction (N x P) x N, where N = X x Y. // // The length of OM can be found using the Pythagorean theorem on triangle // OPM, and the length of MR can be found using the Pythagorean theorem on // triangle OMR. // // In the calculations below, we save some work by scaling all the vectors // by n.CrossProd(p).Norm2(), and normalizing at the end. double n2 = n.Norm2(); double nDp = n.DotProd(p); S2Point nXp = n.CrossProd(p); S2Point nXpXn = n2 * p - nDp * n; Vector3_d om = sqrt(1 - edge_snap_radius_sin2_) * nXpXn; double mr2 = edge_snap_radius_sin2_ * n2 - nDp * nDp; // MR is constructed so that it points toward Y (rather than X). Vector3_d mr = sqrt(max(0.0, mr2)) * nXp; return (om + mr).Normalize(); } void S2Builder::SnapEdge(InputEdgeId e, vector* chain) const { chain->clear(); const InputEdge& edge = input_edges_[e]; if (!snapping_needed_) { // Note that the input vertices have been renumbered such that // InputVertexId and SiteId are the same (see ChooseAllVerticesAsSites). chain->push_back(edge.first); chain->push_back(edge.second); return; } const S2Point& x = input_vertices_[edge.first]; const S2Point& y = input_vertices_[edge.second]; // Optimization: if there is only one nearby site, return. // Optimization: if there are exactly two nearby sites, and one is close // enough to each vertex, then return. // Now iterate through the sites. We keep track of the sequence of sites // that are visited. const auto& candidates = edge_sites_[e]; for (SiteId site_id : candidates) { const S2Point& c = sites_[site_id]; // Skip any sites that are too far away. (There will be some of these, // because we also keep track of "sites to avoid".) Note that some sites // may be close enough to the line containing the edge, but not to the // edge itself, so we can just use the dot product with the edge normal. if (s2pred::CompareEdgeDistance(c, x, y, edge_snap_radius_ca_) > 0) { continue; } // Check whether the new site C excludes the previous site B. If so, // repeat with the previous site, and so on. bool add_site_c = true; for (; !chain->empty(); chain->pop_back()) { S2Point b = sites_[chain->back()]; // First, check whether B and C are so far apart that their clipped // Voronoi regions can't intersect. S1ChordAngle bc(b, c); if (bc >= max_adjacent_site_separation_ca_) break; // Otherwise, we want to check whether site C prevents the Voronoi // region of B from intersecting XY, or vice versa. This can be // determined by computing the "coverage interval" (the segment of XY // intersected by the coverage disc of radius snap_radius) for each // site. If the coverage interval of one site contains the coverage // interval of the other, then the contained site can be excluded. s2pred::Excluded result = s2pred::GetVoronoiSiteExclusion( b, c, x, y, edge_snap_radius_ca_); if (result == s2pred::Excluded::FIRST) continue; // Site B excluded by C if (result == s2pred::Excluded::SECOND) { add_site_c = false; // Site C is excluded by B. break; } ABSL_DCHECK_EQ(s2pred::Excluded::NEITHER, result); // Otherwise check whether the previous site A is close enough to B and // C that it might further clip the Voronoi region of B. if (chain->size() < 2) break; S2Point a = sites_[chain->end()[-2]]; S1ChordAngle ac(a, c); if (ac >= max_adjacent_site_separation_ca_) break; // If triangles ABC and XYB have the same orientation, the circumcenter // Z of ABC is guaranteed to be on the same side of XY as B. int xyb = s2pred::Sign(x, y, b); if (s2pred::Sign(a, b, c) == xyb) { break; // The circumcenter is on the same side as B but further away. } // Other possible optimizations: // - if AB > max_adjacent_site_separation_ca_ then keep B. // - if d(B, XY) < 0.5 * min(AB, BC) then keep B. // If the circumcenter of ABC is on the same side of XY as B, then B is // excluded by A and C combined. Otherwise B is needed and we can exit. if (s2pred::EdgeCircumcenterSign(x, y, a, b, c) != xyb) break; } if (add_site_c) { chain->push_back(site_id); } } ABSL_DCHECK(!chain->empty()); if (S2_DEBUG_MODE) { for (SiteId site_id : candidates) { if (s2pred::CompareDistances(y, sites_[chain->back()], sites_[site_id]) > 0) { ABSL_LOG(ERROR) << "Snapping invariant broken!"; } } } } void S2Builder::BuildLayers() { if (!tracker_.ok()) return; // Each output edge has an "input edge id set id" (an int32_t) representing // the set of input edge ids that were snapped to this edge. The actual // InputEdgeIds can be retrieved using "input_edge_id_set_lexicon". vector> layer_edges; vector> layer_input_edge_ids; IdSetLexicon input_edge_id_set_lexicon; vector> layer_vertices; BuildLayerEdges(&layer_edges, &layer_input_edge_ids, &input_edge_id_set_lexicon); auto _ = absl::MakeCleanup([&]() { for (size_t i = 0; i < layers_.size(); ++i) { tracker_.Untally(layer_edges[i]); tracker_.Untally(layer_input_edge_ids[i]); if (!layer_vertices.empty()) tracker_.Untally(layer_vertices[i]); } }); // If there are a large number of layers, then we build a minimal subset of // vertices for each layer. This ensures that layer types that iterate over // vertices will run in time proportional to the size of that layer rather // than the size of all layers combined. static const int kMinLayersForVertexFiltering = 10; if (layers_.size() >= kMinLayersForVertexFiltering) { // Disable vertex filtering if it is disallowed by any layer. (This could // be optimized, but in current applications either all layers allow // filtering or none of them do.) bool allow_vertex_filtering = true; for (const auto& options : layer_options_) { allow_vertex_filtering &= options.allow_vertex_filtering(); } if (allow_vertex_filtering) { // Track the temporary memory used by FilterVertices(). Note that // although vertex filtering can increase the number of vertices stored // (i.e., if the same vertex is referred to by multiple layers), it // never increases storage quadratically because there can be at most // two filtered vertices per edge. if (!tracker_.TallyFilterVertices(sites_.size(), layer_edges)) return; auto _ = absl::MakeCleanup([this]() { tracker_.DoneFilterVertices(); }); layer_vertices.resize(layers_.size()); vector filter_tmp; // Temporary used by FilterVertices. for (size_t i = 0; i < layers_.size(); ++i) { layer_vertices[i] = Graph::FilterVertices(sites_, &layer_edges[i], &filter_tmp); if (!tracker_.Tally(layer_vertices[i])) return; } tracker_.Clear(&sites_); // Releases memory. } } if (!tracker_.ok()) return; for (size_t i = 0; i < layers_.size(); ++i) { const vector& vertices = (layer_vertices.empty() ? sites_ : layer_vertices[i]); Graph graph(layer_options_[i], &vertices, &layer_edges[i], &layer_input_edge_ids[i], &input_edge_id_set_lexicon, &label_set_ids_, &label_set_lexicon_, layer_is_full_polygon_predicates_[i]); layers_[i]->Build(graph, error_); // Don't free the layer data until all layers have been built, in order to // support building multiple layers at once (e.g. ClosedSetNormalizer). } } // Snaps and possibly simplifies the edges for each layer, populating the // given output arguments. The resulting edges can be used to construct an // S2Builder::Graph directly (no further processing is necessary). // // This method is not "const" because Graph::ProcessEdges can modify // layer_options_ in some cases (changing undirected edges to directed ones). void S2Builder::BuildLayerEdges( vector>* layer_edges, vector>* layer_input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon) { // Edge chains are simplified only when a non-zero snap radius is specified. // If so, we build a map from each site to the set of input vertices that // snapped to that site. (Note that site_vertices is relatively small and // that its memory tracking is deferred until TallySimplifyEdgeChains.) vector> site_vertices; bool simplify = snapping_needed_ && options_.simplify_edge_chains(); if (simplify) site_vertices.resize(sites_.size()); layer_edges->resize(layers_.size()); layer_input_edge_ids->resize(layers_.size()); for (size_t i = 0; i < layers_.size(); ++i) { AddSnappedEdges(layer_begins_[i], layer_begins_[i+1], layer_options_[i], &(*layer_edges)[i], &(*layer_input_edge_ids)[i], input_edge_id_set_lexicon, &site_vertices); } // We simplify edge chains before processing the per-layer GraphOptions // because simplification can create duplicate edges and/or sibling edge // pairs which may need to be removed. if (simplify) { SimplifyEdgeChains(site_vertices, layer_edges, layer_input_edge_ids, input_edge_id_set_lexicon); vector>().swap(site_vertices); } // At this point we have no further need for nearby site data, so we clear // it to save space. We keep input_vertices_ and input_edges_ so that // S2Builder::Layer implementations can access them if desired. (This is // useful for determining how snapping has changed the input geometry.) tracker_.ClearEdgeSites(&edge_sites_); for (size_t i = 0; i < layers_.size(); ++i) { // The errors generated by ProcessEdges are really warnings, so we simply // record them and continue. Graph::ProcessEdges(&layer_options_[i], &(*layer_edges)[i], &(*layer_input_edge_ids)[i], input_edge_id_set_lexicon, error_, &tracker_); if (!tracker_.ok()) return; } } // Snaps all the input edges for a given layer, populating the given output // arguments. If (*site_vertices) is non-empty then it is updated so that // (*site_vertices)[site] contains a list of all input vertices that were // snapped to that site. void S2Builder::AddSnappedEdges( InputEdgeId begin, InputEdgeId end, const GraphOptions& options, vector* edges, vector* input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon, vector>* site_vertices) { bool discard_degenerate_edges = (options.degenerate_edges() == GraphOptions::DegenerateEdges::DISCARD); vector chain; for (InputEdgeId e = begin; e < end; ++e) { InputEdgeIdSetId id = input_edge_id_set_lexicon->AddSingleton(e); SnapEdge(e, &chain); if (chain.empty()) { continue; } int num_snapped_edges = max(1, chain.size() - 1); if (options.edge_type() == EdgeType::UNDIRECTED) num_snapped_edges *= 2; if (!tracker_.AddSpace(edges, num_snapped_edges)) return; if (!tracker_.AddSpace(input_edge_ids, num_snapped_edges)) return; MaybeAddInputVertex(input_edges_[e].first, chain[0], site_vertices); if (chain.size() == 1) { if (discard_degenerate_edges) continue; AddSnappedEdge(chain[0], chain[0], id, options.edge_type(), edges, input_edge_ids); } else { MaybeAddInputVertex(input_edges_[e].second, chain.back(), site_vertices); for (size_t i = 1; i < chain.size(); ++i) { AddSnappedEdge(chain[i-1], chain[i], id, options.edge_type(), edges, input_edge_ids); } } } } // If "site_vertices" is non-empty, ensures that (*site_vertices)[id] contains // "v". Duplicate entries are allowed. The purpose of this function is to // build a map so that SimplifyEdgeChains() can quickly find all the input // vertices that snapped to a particular site. inline void S2Builder::MaybeAddInputVertex( InputVertexId v, SiteId id, vector>* site_vertices) const { if (site_vertices->empty()) return; // Optimization: check if we just added this vertex. This is worthwhile // because the input edges usually form a continuous chain, i.e. the // destination of one edge is the same as the source of the next edge. auto& vertices = (*site_vertices)[id]; if (vertices.empty() || vertices.back() != v) { // Memory tracking is deferred until SimplifyEdgeChains. vertices.push_back(v); } } // Adds the given edge to "edges" and "input_edge_ids". If undirected edges // are being used, also adds an edge in the opposite direction. inline void S2Builder::AddSnappedEdge( SiteId src, SiteId dst, InputEdgeIdSetId id, EdgeType edge_type, vector* edges, vector* input_edge_ids) const { edges->push_back(Edge(src, dst)); input_edge_ids->push_back(id); if (edge_type == EdgeType::UNDIRECTED) { edges->push_back(Edge(dst, src)); // Automatically created edges do not have input edge ids or labels. This // can be used to distinguish the original direction of the undirected edge. input_edge_ids->push_back(IdSetLexicon::EmptySetId()); } } // A class that encapsulates the state needed for simplifying edge chains. class S2Builder::EdgeChainSimplifier { public: // The graph "g" contains all edges from all layers. "edge_layers" // indicates the original layer for each edge. "site_vertices" is a map // from SiteId to the set of InputVertexIds that were snapped to that site. // "layer_edges" and "layer_input_edge_ids" are output arguments where the // simplified edge chains will be placed. The input and output edges are // not sorted. EdgeChainSimplifier( const S2Builder& builder, const Graph& g, const vector& edge_layers, const vector>& site_vertices, vector>* layer_edges, vector>* layer_input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon); void Run(); private: using VertexId = Graph::VertexId; class InteriorVertexMatcher; void OutputEdge(EdgeId e); int graph_edge_layer(EdgeId e) const; int input_edge_layer(InputEdgeId id) const; bool IsInterior(VertexId v); void SimplifyChain(VertexId v0, VertexId v1); Graph::VertexId FollowChain(VertexId v0, VertexId v1) const; void OutputAllEdges(VertexId v0, VertexId v1); bool TargetInputVertices(VertexId v, S2PolylineSimplifier* simplifier) const; bool AvoidSites(VertexId v0, VertexId v1, VertexId v2, flat_hash_set* used_vertices, S2PolylineSimplifier* simplifier) const; void MergeChain(absl::Span vertices); void AssignDegenerateEdges(absl::Span degenerate_ids, vector>* merged_ids) const; // LINT.IfChange const S2Builder& builder_; const Graph& g_; Graph::VertexInMap in_; Graph::VertexOutMap out_; const vector& edge_layers_; const vector>& site_vertices_; vector>* layer_edges_; vector>* layer_input_edge_ids_; IdSetLexicon* input_edge_id_set_lexicon_; // Convenience member copied from builder_. const vector& layer_begins_; // is_interior_[v] indicates that VertexId "v" is eligible to be an interior // vertex of a simplified edge chain. You can think of it as vertex whose // indegree and outdegree are both 1 (although the actual definition is a // bit more complicated because of duplicate edges and layers). vector is_interior_; // used_[e] indicates that EdgeId "e" has already been processed. vector used_; // Temporary objects declared here to avoid repeated allocation. vector tmp_vertices_; vector tmp_edges_; flat_hash_set tmp_vertex_set_; // The output edges after simplification. vector new_edges_; vector new_input_edge_ids_; vector new_edge_layers_; }; // Simplifies edge chains, updating its input/output arguments as necessary. void S2Builder::SimplifyEdgeChains( const vector>& site_vertices, vector>* layer_edges, vector>* layer_input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon) { if (layers_.empty()) return; if (!tracker_.TallySimplifyEdgeChains(site_vertices, *layer_edges)) return; // Merge the edges from all layers (in order to build a single graph). vector merged_edges; vector merged_input_edge_ids; vector merged_edge_layers; MergeLayerEdges(*layer_edges, *layer_input_edge_ids, &merged_edges, &merged_input_edge_ids, &merged_edge_layers); // The following fields will be reconstructed by EdgeChainSimplifier. for (auto& edges : *layer_edges) edges.clear(); for (auto& input_edge_ids : *layer_input_edge_ids) input_edge_ids.clear(); // The graph options are irrelevant for edge chain simplification, but we // try to set them appropriately anyway. S2Builder::GraphOptions graph_options(EdgeType::DIRECTED, GraphOptions::DegenerateEdges::KEEP, GraphOptions::DuplicateEdges::KEEP, GraphOptions::SiblingPairs::KEEP); Graph graph(graph_options, &sites_, &merged_edges, &merged_input_edge_ids, input_edge_id_set_lexicon, nullptr, nullptr, IsFullPolygonPredicate()); EdgeChainSimplifier simplifier( *this, graph, merged_edge_layers, site_vertices, layer_edges, layer_input_edge_ids, input_edge_id_set_lexicon); simplifier.Run(); } // LINT.ThenChange(:TallySimplifyEdgeChains) // Merges the edges from all layers and sorts them in lexicographic order so // that we can construct a single graph. The sort is stable, which means that // any duplicate edges within each layer will still be sorted by InputEdgeId. void S2Builder::MergeLayerEdges( absl::Span> layer_edges, absl::Span> layer_input_edge_ids, vector* edges, vector* input_edge_ids, vector* edge_layers) const { vector order; for (size_t i = 0; i < layer_edges.size(); ++i) { for (size_t e = 0; e < layer_edges[i].size(); ++e) { order.push_back(LayerEdgeId(i, e)); } } std::sort(order.begin(), order.end(), [layer_edges](const LayerEdgeId& ai, const LayerEdgeId& bi) { return StableLessThan(layer_edges[ai.first][ai.second], layer_edges[bi.first][bi.second], ai, bi); }); edges->reserve(order.size()); input_edge_ids->reserve(order.size()); edge_layers->reserve(order.size()); for (const LayerEdgeId& id : order) { edges->push_back(layer_edges[id.first][id.second]); input_edge_ids->push_back(layer_input_edge_ids[id.first][id.second]); edge_layers->push_back(id.first); } } // A comparison function that allows stable sorting with std::sort (which is // fast but not stable). It breaks ties between equal edges by comparing // their LayerEdgeIds. inline bool S2Builder::StableLessThan( const Edge& a, const Edge& b, const LayerEdgeId& ai, const LayerEdgeId& bi) { // The compiler doesn't optimize this as well as it should: // return std::make_pair(a, ai) < std::make_pair(b, bi); if (a.first < b.first) return true; if (b.first < a.first) return false; if (a.second < b.second) return true; if (b.second < a.second) return false; return ai < bi; // Stable sort. } S2Builder::EdgeChainSimplifier::EdgeChainSimplifier( const S2Builder& builder, const Graph& g, const vector& edge_layers, const vector>& site_vertices, vector>* layer_edges, vector>* layer_input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon) : builder_(builder), g_(g), in_(g), out_(g), edge_layers_(edge_layers), site_vertices_(site_vertices), layer_edges_(layer_edges), layer_input_edge_ids_(layer_input_edge_ids), input_edge_id_set_lexicon_(input_edge_id_set_lexicon), layer_begins_(builder_.layer_begins_), is_interior_(g.num_vertices()), used_(g.num_edges()), // See `AddExtraSites` for explanation of `bucket_count`. tmp_vertex_set_(/*bucket_count=*/18) { new_edges_.reserve(g.num_edges()); new_input_edge_ids_.reserve(g.num_edges()); new_edge_layers_.reserve(g.num_edges()); } void S2Builder::EdgeChainSimplifier::Run() { // Determine which vertices can be interior vertices of an edge chain. for (VertexId v = 0; v < g_.num_vertices(); ++v) { is_interior_[v] = IsInterior(v); } // Attempt to simplify all edge chains that start from a non-interior // vertex. (This takes care of all chains except loops.) for (EdgeId e = 0; e < g_.num_edges(); ++e) { if (used_[e]) continue; Edge edge = g_.edge(e); if (is_interior_[edge.first]) continue; if (!is_interior_[edge.second]) { OutputEdge(e); // An edge between two non-interior vertices. } else { SimplifyChain(edge.first, edge.second); } } // If there are any edges left, they form one or more disjoint loops where // all vertices are interior vertices. // // TODO(ericv): It would be better to start from the edge with the smallest // min_input_edge_id(), since that would make the output more predictable // for testing purposes. It also means that we won't create an edge that // spans the start and end of a polyline if the polyline is snapped into a // loop. (Unfortunately there are pathological examples that prevent us // from guaranteeing this in general, e.g. there could be two polylines in // different layers that snap to the same loop but start at different // positions. In general we only consider input edge ids to be a hint // towards the preferred output ordering.) for (EdgeId e = 0; e < g_.num_edges(); ++e) { if (used_[e]) continue; Edge edge = g_.edge(e); if (edge.first == edge.second) { // Note that it is safe to output degenerate edges as we go along, // because this vertex has at least one non-degenerate outgoing edge and // therefore we will (or just did) start an edge chain here. OutputEdge(e); } else { SimplifyChain(edge.first, edge.second); } } // TODO(ericv): The graph is not needed past here, so we could save some // memory by clearing the underlying Edge and InputEdgeIdSetId vectors. // Finally, copy the output edges into the appropriate layers. They don't // need to be sorted because the input edges were also unsorted. for (size_t e = 0; e < new_edges_.size(); ++e) { int layer = new_edge_layers_[e]; (*layer_edges_)[layer].push_back(new_edges_[e]); (*layer_input_edge_ids_)[layer].push_back(new_input_edge_ids_[e]); } } // Copies the given edge to the output and marks it as used. inline void S2Builder::EdgeChainSimplifier::OutputEdge(EdgeId e) { new_edges_.push_back(g_.edge(e)); new_input_edge_ids_.push_back(g_.input_edge_id_set_id(e)); new_edge_layers_.push_back(edge_layers_[e]); used_[e] = true; } // Returns the layer that a given graph edge belongs to. inline int S2Builder::EdgeChainSimplifier::graph_edge_layer(EdgeId e) const { return edge_layers_[e]; } // Returns the layer than a given input edge belongs to. int S2Builder::EdgeChainSimplifier::input_edge_layer(InputEdgeId id) const { // NOTE(ericv): If this method shows up in profiling, the result could be // stored with each edge (i.e., edge_layers_ and new_edge_layers_). ABSL_DCHECK_GE(id, 0); return (std::upper_bound(layer_begins_.begin(), layer_begins_.end(), id) - (layer_begins_.begin() + 1)); } // A helper class for determining whether a vertex can be an interior vertex // of a simplified edge chain. Such a vertex must be adjacent to exactly two // vertices (across all layers combined), and in each layer the number of // incoming edges from one vertex must equal the number of outgoing edges to // the other vertex (in both directions). Furthermore the vertex cannot have // any degenerate edges in a given layer unless it has at least one // non-degenerate edge in that layer as well. (Note that usually there will // not be any degenerate edges at all, since most layer types discard them.) // // The last condition is necessary to prevent the following: suppose that one // layer has a chain ABC and another layer has a degenerate edge BB (with no // other edges incident to B). Then we can't simplify ABC to AC because there // would be no suitable replacement for the edge BB (since the input edge that // mapped to BB can't be replaced by any of the edges AA, AC, or CC without // moving further than snap_radius). class S2Builder::EdgeChainSimplifier::InteriorVertexMatcher { public: // Checks whether "v0" can be an interior vertex of an edge chain. explicit InteriorVertexMatcher(VertexId v0) : v0_(v0) {} // Starts analyzing the edges of a new layer. void StartLayer() { excess_out_ = n0_ = n1_ = n2_ = 0; } // This method should be called for each edge incident to "v0" in a given // layer. (For degenerate edges, it should be called twice.) void Tally(VertexId v, bool outgoing) { excess_out_ += outgoing ? 1 : -1; // outdegree - indegree if (v == v0_) { ++n0_; // Counts both endpoints of each degenerate edge. } else { // We keep track of the total number of edges (incoming or outgoing) // connecting v0 to up to two adjacent vertices. if (v1_ < 0) v1_ = v; if (v1_ == v) { ++n1_; } else { if (v2_ < 0) v2_ = v; if (v2_ == v) { ++n2_; } else { too_many_endpoints_ = true; } } } } // This method should be called after processing the edges for each layer. // It returns true if "v0" is an interior vertex based on the edges so far. bool Matches() const { // We check that there are the same number of incoming and outgoing edges // in each direction by verifying that (1) indegree(v0) == outdegree(v0) // and (2) the total number of edges (incoming and outgoing) to "v1" and // "v2" are equal. We also check the condition on degenerate edges that // is documented above. return (!too_many_endpoints_ && excess_out_ == 0 && n1_ == n2_ && (n0_ == 0 || n1_ > 0)); } private: VertexId v0_ = -1, v1_ = -1, v2_ = -1; int n0_ = 0, n1_ = 0, n2_ = 0; int excess_out_ = 0; // outdegree(v0) - indegree(v0) // Have we seen more than two adjacent vertices? bool too_many_endpoints_ = false; }; // Returns true if VertexId "v" can be an interior vertex of a simplified edge // chain. (See the InteriorVertexMatcher class for what this implies.) bool S2Builder::EdgeChainSimplifier::IsInterior(VertexId v) { // Check a few simple prerequisites. if (out_.degree(v) == 0) return false; if (out_.degree(v) != in_.degree(v)) return false; if (builder_.is_forced(v)) return false; // Keep forced vertices. // Sort the edges so that they are grouped by layer. vector& edges = tmp_edges_; // Avoid allocating each time. edges.clear(); for (EdgeId e : out_.edge_ids(v)) edges.push_back(e); for (EdgeId e : in_.edge_ids(v)) edges.push_back(e); std::sort(edges.begin(), edges.end(), [this](EdgeId x, EdgeId y) { return graph_edge_layer(x) < graph_edge_layer(y); }); // Now feed the edges in each layer to the InteriorVertexMatcher. InteriorVertexMatcher matcher(v); for (auto e = edges.begin(); e != edges.end(); ) { int layer = graph_edge_layer(*e); matcher.StartLayer(); for (; e != edges.end() && graph_edge_layer(*e) == layer; ++e) { Edge edge = g_.edge(*e); if (edge.first == v) matcher.Tally(edge.second, true /*outgoing*/); if (edge.second == v) matcher.Tally(edge.first, false /*outgoing*/); } if (!matcher.Matches()) return false; } return true; } // Follows the edge chain starting with (v0, v1) until either we find a // non-interior vertex or we return to the original vertex v0. At each vertex // we simplify a subchain of edges that is as long as possible. void S2Builder::EdgeChainSimplifier::SimplifyChain(VertexId v0, VertexId v1) { // Avoid allocating "chain" each time by reusing it. vector& chain = tmp_vertices_; // Contains the set of vertices that have either been avoided or added to // the chain so far. This is necessary so that AvoidSites() doesn't try to // avoid vertices that have already been added to the chain. flat_hash_set& used_vertices = tmp_vertex_set_; S2PolylineSimplifier simplifier; VertexId vstart = v0; bool done = false; do { // Simplify a subchain of edges starting with (v0, v1). chain.push_back(v0); used_vertices.insert(v0); simplifier.Init(g_.vertex(v0)); // Note that if the first edge (v0, v1) is longer than the maximum length // allowed for simplification, then AvoidSites() will return false and we // exit the loop below after the first iteration. const bool simplify = AvoidSites(v0, v0, v1, &used_vertices, &simplifier); do { chain.push_back(v1); used_vertices.insert(v1); done = !is_interior_[v1] || v1 == vstart; if (done) break; // Attempt to extend the chain to the next vertex. VertexId vprev = v0; v0 = v1; v1 = FollowChain(vprev, v0); } while (simplify && TargetInputVertices(v0, &simplifier) && AvoidSites(chain[0], v0, v1, &used_vertices, &simplifier) && simplifier.Extend(g_.vertex(v1))); if (chain.size() == 2) { OutputAllEdges(chain[0], chain[1]); // Could not simplify. } else { MergeChain(chain); } // Note that any degenerate edges that were not merged into a chain are // output by EdgeChainSimplifier::Run(). chain.clear(); used_vertices.clear(); } while (!done); } // Given an edge (v0, v1) where v1 is an interior vertex, returns the (unique) // next vertex in the edge chain. S2Builder::Graph::VertexId S2Builder::EdgeChainSimplifier::FollowChain( VertexId v0, VertexId v1) const { ABSL_DCHECK(is_interior_[v1]); for (EdgeId e : out_.edge_ids(v1)) { VertexId v = g_.edge(e).second; if (v != v0 && v != v1) return v; } ABSL_LOG(FATAL) << "Could not find next edge in edge chain"; } // Copies all input edges between v0 and v1 (in both directions) to the output. void S2Builder::EdgeChainSimplifier::OutputAllEdges(VertexId v0, VertexId v1) { for (EdgeId e : out_.edge_ids(v0, v1)) OutputEdge(e); for (EdgeId e : out_.edge_ids(v1, v0)) OutputEdge(e); } // Ensures that the simplified edge passes within "edge_snap_radius" of all // the *input* vertices that snapped to the given vertex "v". bool S2Builder::EdgeChainSimplifier::TargetInputVertices( VertexId v, S2PolylineSimplifier* simplifier) const { for (InputVertexId i : site_vertices_[v]) { if (!simplifier->TargetDisc(builder_.input_vertices_[i], builder_.edge_snap_radius_ca_)) { return false; } } return true; } // Given the starting vertex v0 and last edge (v1, v2) of an edge chain, // restricts the allowable range of angles in order to ensure that all sites // near the edge (v1, v2) are avoided by at least min_edge_vertex_separation. bool S2Builder::EdgeChainSimplifier::AvoidSites( VertexId v0, VertexId v1, VertexId v2, flat_hash_set* used_vertices, S2PolylineSimplifier* simplifier) const { const S2Point& p0 = g_.vertex(v0); const S2Point& p1 = g_.vertex(v1); const S2Point& p2 = g_.vertex(v2); S1ChordAngle r1(p0, p1); S1ChordAngle r2(p0, p2); // The distance from the start of the edge chain must increase monotonically // for each vertex, since we don't want to simplify chains that backtrack on // themselves (we want a parametric approximation, not a geometric one). if (r2 < r1) return false; // We also limit the maximum edge length in order to guarantee that the // simplified edge stays with max_edge_deviation() of all the input edges // that snap to it. if (r2 >= builder_.min_edge_length_to_split_ca_) return false; // Otherwise it is sufficient to consider the nearby sites (edge_sites_) for // a single input edge that snapped to (v1, v2) or (v2, v1). This is // because each edge has a list of all sites within (max_edge_deviation + // min_edge_vertex_separation), and since the output edge is within // max_edge_deviation of all input edges, this list includes all sites // within min_edge_vertex_separation of the output edge. // // Usually there is only one edge to choose from, but it's not much more // effort to choose the edge with the shortest list of edge_sites_. InputEdgeId best = -1; const auto& edge_sites = builder_.edge_sites_; for (EdgeId e : out_.edge_ids(v1, v2)) { for (InputEdgeId id : g_.input_edge_ids(e)) { if (best < 0 || edge_sites[id].size() < edge_sites[best].size()) best = id; } } for (EdgeId e : out_.edge_ids(v2, v1)) { for (InputEdgeId id : g_.input_edge_ids(e)) { if (best < 0 || edge_sites[id].size() < edge_sites[best].size()) best = id; } } ABSL_DCHECK_GE(best, 0); // Because there is at least one outgoing edge. for (VertexId v : edge_sites[best]) { // Sites whose distance from "p0" is at least "r2" are not relevant yet. const S2Point& p = g_.vertex(v); S1ChordAngle r(p0, p); if (r >= r2) continue; // The following test prevents us from avoiding previous vertices of the // edge chain that also happen to be nearby the current edge. (It also // happens to ensure that each vertex is avoided at most once, but this is // just an optimization.) if (!used_vertices->insert(v).second) continue; // We need to figure out whether this site is to the left or right of the // edge chain. For the first edge this is easy. Otherwise, since we are // only considering sites in the radius range (r1, r2), we can do this by // checking whether the site is to the left of the wedge (p0, p1, p2). bool disc_on_left = (v1 == v0) ? (s2pred::Sign(p1, p2, p) > 0) : s2pred::OrderedCCW(p0, p2, p, p1); if (!simplifier->AvoidDisc(p, builder_.min_edge_site_separation_ca_, disc_on_left)) { return false; } } return true; } // Given the vertices in a simplified edge chain, adds the corresponding // simplified edge(s) to the output. Note that (1) the edge chain may exist // in multiple layers, (2) the edge chain may exist in both directions, (3) // there may be more than one copy of an edge chain (in either direction) // within a single layer. void S2Builder::EdgeChainSimplifier::MergeChain( absl::Span vertices) { // Suppose that all interior vertices have M outgoing edges and N incoming // edges. Our goal is to group the edges into M outgoing chains and N // incoming chains, and then replace each chain by a single edge. vector> merged_input_ids; vector degenerate_ids; int num_out; // Edge count in the outgoing direction. for (size_t i = 1; i < vertices.size(); ++i) { VertexId v0 = vertices[i-1]; VertexId v1 = vertices[i]; auto out_edges = out_.edge_ids(v0, v1); auto in_edges = out_.edge_ids(v1, v0); if (i == 1) { // Allocate space to store the input edge ids associated with each edge. num_out = out_edges.size(); merged_input_ids.resize(num_out + in_edges.size()); for (vector& ids : merged_input_ids) { ids.reserve(vertices.size() - 1); } } else { // For each interior vertex, we build a list of input edge ids // associated with degenerate edges. Each input edge ids will be // assigned to one of the output edges later. (Normally there are no // degenerate edges at all since most layer types don't want them.) ABSL_DCHECK(is_interior_[v0]); for (EdgeId e : out_.edge_ids(v0, v0)) { for (InputEdgeId id : g_.input_edge_ids(e)) { degenerate_ids.push_back(id); } used_[e] = true; } } // Because the edges were created in layer order, and all sorts used are // stable, the edges are still in layer order. Therefore we can simply // merge together all the edges in the same relative position. int j = 0; for (EdgeId e : out_edges) { for (InputEdgeId id : g_.input_edge_ids(e)) { merged_input_ids[j].push_back(id); } used_[e] = true; ++j; } for (EdgeId e : in_edges) { for (InputEdgeId id : g_.input_edge_ids(e)) { merged_input_ids[j].push_back(id); } used_[e] = true; ++j; } ABSL_DCHECK_EQ(merged_input_ids.size(), j); } if (!degenerate_ids.empty()) { std::sort(degenerate_ids.begin(), degenerate_ids.end()); AssignDegenerateEdges(degenerate_ids, &merged_input_ids); } // Output the merged edges. VertexId v0 = vertices[0], v1 = vertices[1], vb = vertices.back(); for (EdgeId e : out_.edge_ids(v0, v1)) { new_edges_.push_back(Edge(v0, vb)); new_edge_layers_.push_back(graph_edge_layer(e)); } for (EdgeId e : out_.edge_ids(v1, v0)) { new_edges_.push_back(Edge(vb, v0)); new_edge_layers_.push_back(graph_edge_layer(e)); } for (const auto& ids : merged_input_ids) { new_input_edge_ids_.push_back(input_edge_id_set_lexicon_->Add(ids)); } } // Given a list of the input edge ids associated with degenerate edges in the // interior of an edge chain, assigns each input edge id to one of the output // edges. void S2Builder::EdgeChainSimplifier::AssignDegenerateEdges( absl::Span degenerate_ids, vector>* merged_ids) const { // Each degenerate edge is assigned to an output edge in the appropriate // layer. If there is more than one candidate, we use heuristics so that if // the input consists of a chain of edges provided in consecutive order // (some of which became degenerate), then all those input edges are // assigned to the same output edge. For example, suppose that one output // edge is labeled with input edges 3,4,7,8, while another output edge is // labeled with input edges 50,51,54,57. Then if we encounter degenerate // edges labeled with input edges 5 and 6, we would prefer to assign them to // the first edge (yielding the continuous range 3,4,5,6,7,8). // // The heuristic below is only smart enough to handle the case where the // candidate output edges have non-overlapping ranges of input edges. // (Otherwise there is probably not a good heuristic for assigning the // degenerate edges in any case.) // Duplicate edge ids don't affect the heuristic below, so we don't bother // removing them. (They will be removed by IdSetLexicon::Add.) for (auto& ids : *merged_ids) std::sort(ids.begin(), ids.end()); // Sort the output edges by their minimum input edge id. This is sufficient // for the purpose of determining which layer they belong to. With // EdgeType::UNDIRECTED, some edges might not have any input edge ids (i.e., // if they consist entirely of siblings of input edges). We simply remove // such edges from the lists of candidates. vector order; order.reserve(merged_ids->size()); for (size_t i = 0; i < merged_ids->size(); ++i) { if (!(*merged_ids)[i].empty()) order.push_back(i); } std::sort(order.begin(), order.end(), [&merged_ids](int i, int j) { return (*merged_ids)[i][0] < (*merged_ids)[j][0]; }); // Now determine where each degenerate edge should be assigned. for (InputEdgeId degenerate_id : degenerate_ids) { int layer = input_edge_layer(degenerate_id); // Find the first output edge whose range of input edge ids starts after // "degenerate_id". If the previous edge belongs to the correct layer, // then we assign the degenerate edge to it. auto it = std::upper_bound(order.begin(), order.end(), degenerate_id, [&merged_ids](InputEdgeId x, unsigned y) { return x < (*merged_ids)[y][0]; }); if (it != order.begin()) { if ((*merged_ids)[it[-1]][0] >= layer_begins_[layer]) --it; } ABSL_DCHECK_EQ(layer, input_edge_layer((*merged_ids)[it[0]][0])); (*merged_ids)[it[0]].push_back(degenerate_id); } } /////////////////////// S2Builder::MemoryTracker ///////////////////////// // Called to track memory used to store the set of sites near a given edge. bool S2Builder::MemoryTracker::TallyEdgeSites( const compact_array& sites) { int64_t size = GetCompactArrayAllocBytes(sites); edge_sites_bytes_ += size; return Tally(size); } // Ensures that "sites" contains space for at least one more edge site. bool S2Builder::MemoryTracker::ReserveEdgeSite(compact_array* sites) { int64_t new_size = sites->size() + 1; if (new_size <= sites->capacity()) return true; int64_t old_bytes = GetCompactArrayAllocBytes(*sites); sites->reserve(new_size); int64_t added_bytes = GetCompactArrayAllocBytes(*sites) - old_bytes; edge_sites_bytes_ += added_bytes; return Tally(added_bytes); } // Releases and tracks the memory used to store nearby edge sites. bool S2Builder::MemoryTracker::ClearEdgeSites( vector>* edge_sites) { Tally(-edge_sites_bytes_); edge_sites_bytes_ = 0; return Clear(edge_sites); } // Called when a site is added to the S2PointIndex. bool S2Builder::MemoryTracker::TallyIndexedSite() { // S2PointIndex stores its data in a btree. In general btree nodes are only // guaranteed to be half full, but in our case all nodes are full except for // the rightmost node at each btree level because the values are added in // sorted order. int64_t delta_bytes = GetBtreeMinBytesPerEntry< absl::btree_multimap::PointData>>(); site_index_bytes_ += delta_bytes; return Tally(delta_bytes); } // Corrects the approximate S2PointIndex memory tracking done above. bool S2Builder::MemoryTracker::FixSiteIndexTally( const S2PointIndex& index) { int64_t delta_bytes = index.SpaceUsed() - site_index_bytes_; site_index_bytes_ += delta_bytes; return Tally(delta_bytes); } // Tracks memory due to destroying the site index. bool S2Builder::MemoryTracker::DoneSiteIndex( const S2PointIndex& index) { Tally(-site_index_bytes_); site_index_bytes_ = 0; return ok(); } // Called to indicate that edge simplification was requested. // LINT.IfChange(TallySimplifyEdgeChains) bool S2Builder::MemoryTracker::TallySimplifyEdgeChains( absl::Span> site_vertices, absl::Span> layer_edges) { if (!is_active()) return true; // The simplify_edge_chains() option uses temporary memory per site // (output vertex) and per output edge, as outlined below. // // Per site: // vector> site_vertices; // BuildLayerEdges // - compact_array non-inlined space is tallied separately // vector is_interior_; // EdgeChainSimplifier // Graph::VertexInMap in_; // EdgeChainSimplifier // Graph::VertexOutMap out_; // EdgeChainSimplifier const int64_t kTempPerSite = sizeof(compact_array) + sizeof(bool) + 2 * sizeof(EdgeId); // Per output edge: // vector used_; // EdgeChainSimplifier // Graph::VertexInMap in_; // EdgeChainSimplifier // vector merged_edges; // SimplifyEdgeChains // vector merged_input_edge_ids; // SimplifyEdgeChains // vector merged_edge_layers; // SimplifyEdgeChains // vector new_edges_; // EdgeChainSimplifier // vector new_input_edge_ids_; // EdgeChainSimplifier // vector new_edge_layers_; // EdgeChainSimplifier // // Note that the temporary vector in MergeLayerEdges() does not // affect peak usage. const int64_t kTempPerEdge = sizeof(bool) + sizeof(EdgeId) + 2 * sizeof(Edge) + 2 * sizeof(InputEdgeIdSetId) + 2 * sizeof(int); int64_t simplify_bytes = site_vertices.size() * kTempPerSite; for (const auto& array : site_vertices) { simplify_bytes += GetCompactArrayAllocBytes(array); } for (const auto& edges : layer_edges) { simplify_bytes += edges.size() * kTempPerEdge; } return TallyTemp(simplify_bytes); } // LINT.ThenChange() // Tracks the temporary memory used by Graph::FilterVertices. // LINT.IfChange(TallyFilterVertices) bool S2Builder::MemoryTracker::TallyFilterVertices( int num_sites, absl::Span> layer_edges) { if (!is_active()) return true; // Vertex filtering (see BuildLayers) uses temporary space of one VertexId // per Voronoi site plus 2 VertexIds per layer edge, plus space for all the // vertices after filtering. // // vector *tmp; // Graph::FilterVertices // vector used; // Graph::FilterVertices const int64_t kTempPerSite = sizeof(Graph::VertexId); const int64_t kTempPerEdge = 2 * sizeof(Graph::VertexId); size_t max_layer_edges = 0; for (const auto& edges : layer_edges) { max_layer_edges = max(max_layer_edges, edges.size()); } filter_vertices_bytes_ = (num_sites * kTempPerSite + max_layer_edges * kTempPerEdge); return Tally(filter_vertices_bytes_); } // LINT.ThenChange() bool S2Builder::MemoryTracker::DoneFilterVertices() { Tally(-filter_vertices_bytes_); filter_vertices_bytes_ = 0; return ok(); } src/s2/s2builder.h000066400000000000000000001665661524103652300142620ustar00rootroot00000000000000// Copyright 2016 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) // // This class is a replacement for S2PolygonBuilder. Once all clients have // been updated to use this class, S2PolygonBuilder will be removed. #ifndef S2_S2BUILDER_H_ #define S2_S2BUILDER_H_ #include #include #include #include #include #include #include "absl/base/macros.h" #include "absl/base/nullability.h" #include "absl/container/flat_hash_set.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/types/span.h" #include "s2/_fp_contract_off.h" // IWYU pragma: keep #include "s2/id_set_lexicon.h" #include "s2/mutable_s2shape_index.h" #include "s2/s1angle.h" #include "s2/s1chord_angle.h" #include "s2/s2cell_id.h" #include "s2/s2edge_crossings.h" #include "s2/s2edge_distances.h" #include "s2/s2error.h" #include "s2/s2memory_tracker.h" #include "s2/s2point.h" #include "s2/s2point_index.h" #include "s2/s2point_span.h" #include "s2/s2shape.h" #include "s2/s2shape_index.h" #include "s2/util/gtl/compact_array.h" class S2Loop; class S2Polygon; class S2Polyline; // S2Builder is a tool for assembling polygonal geometry from edges. Here are // some of the things it is designed for: // // 1. Building polygons, polylines, and polygon meshes from unsorted // collections of edges. // // 2. Snapping geometry to discrete representations (such as S2CellId centers // or E7 lat/lng coordinates) while preserving the input topology and with // guaranteed error bounds. // // 3. Simplifying geometry (e.g. for indexing, display, or storage). // // 4. Importing geometry from other formats, including repairing geometry // that has errors. // // 5. As a tool for implementing more complex operations such as polygon // intersections and unions. // // The implementation is based on the framework of "snap rounding". Unlike // most snap rounding implementations, S2Builder defines edges as geodesics on // the sphere (straight lines) and uses the topology of the sphere (i.e., // there are no "seams" at the poles or 180th meridian). The algorithm is // designed to be 100% robust for arbitrary input geometry. It offers the // following properties: // // - Guaranteed bounds on how far input vertices and edges can move during // the snapping process (i.e., at most the given "snap_radius"). // // - Guaranteed minimum separation between edges and vertices other than // their endpoints (similar to the goals of Iterated Snap Rounding). In // other words, edges that do not intersect in the output are guaranteed // to have a minimum separation between them. // // - Idempotency (similar to the goals of Stable Snap Rounding), i.e. if the // input already meets the output criteria then it will not be modified. // // - Preservation of the input topology (up to the creation of // degeneracies). This means that there exists a continuous deformation // from the input to the output such that no vertex crosses an edge. In // other words, self-intersections won't be created, loops won't change // orientation, etc. // // - The ability to snap to arbitrary discrete point sets (such as S2CellId // centers, E7 lat/lng points on the sphere, or simply a subset of the // input vertices), rather than being limited to an integer grid. // // Here are some of its other features: // // - It can handle both directed and undirected edges. Undirected edges can // be useful for importing data from other formats, e.g. where loops have // unspecified orientations. // // - It can eliminate self-intersections by finding all edge pairs that cross // and adding a new vertex at each intersection point. // // - It can simplify polygons to within a specified tolerance. For example, // if two vertices are close enough they will be merged, and if an edge // passes nearby a vertex then it will be rerouted through that vertex. // Optionally, it can also detect nearly straight chains of short edges and // replace them with a single long edge, while maintaining the same // accuracy, separation, and topology guarantees ("simplify_edge_chains"). // // - It supports many different output types through the concept of "layers" // (polylines, polygons, polygon meshes, etc). You can build multiple // layers at once in order to ensure that snapping does not create // intersections between different objects (for example, you can simplify a // set of contour lines without the risk of having them cross each other). // // - It supports edge labels, which allow you to attach arbitrary information // to edges and have it preserved during the snapping process. (This can // also be achieved using layers, at a coarser level of granularity.) // // Caveats: // // - Because S2Builder only works with edges, it cannot distinguish between // the empty and full polygons. If your application can generate both the // empty and full polygons, you must implement logic outside of this class. // // Example showing how to snap a polygon to E7 coordinates: // // using s2builderutil::IntLatLngSnapFunction; // S2Builder builder(S2Builder::Options(IntLatLngSnapFunction(7))); // S2Polygon output; // builder.StartLayer(std::make_unique(&output)); // builder.AddPolygon(input); // S2Error error; // if (!builder.Build(&error)) { // ABSL_LOG(ERROR) << error; // ... // } class S2Builder { public: // Indicates whether the input edges are undirected. Typically this is // specified for each output layer (e.g., s2builderutil::S2PolygonLayer). // // Directed edges are preferred, since otherwise the output is ambiguous. // For example, output polygons may be the *inverse* of the intended result // (e.g., a polygon intended to represent the world's oceans may instead // represent the world's land masses). Directed edges are also somewhat // more efficient. // // However even with undirected edges, most S2Builder layer types try to // preserve the input edge direction whenever possible. Generally, edges // are reversed only when it would yield a simpler output. For example, // S2PolygonLayer assumes that polygons created from undirected edges should // cover at most half of the sphere. Similarly, S2PolylineVectorLayer // assembles edges into as few polylines as possible, even if this means // reversing some of the "undirected" input edges. // // For shapes with interiors, directed edges should be oriented so that the // interior is to the left of all edges. This means that for a polygon with // holes, the outer loops ("shells") should be directed counter-clockwise // while the inner loops ("holes") should be directed clockwise. Note that // S2Builder::AddPolygon() follows this convention automatically. enum class EdgeType : uint8_t { DIRECTED, UNDIRECTED }; // A SnapFunction restricts the locations of the output vertices. For // example, there are predefined snap functions that require vertices to be // located at S2CellId centers or at E5/E6/E7 coordinates. The SnapFunction // can also specify a minimum spacing between vertices (the "snap radius"). // // A SnapFunction defines the following methods: // // 1. The SnapPoint() method, which snaps a point P to a nearby point (the // "candidate snap site"). Any point may be returned, including P // itself (this is the "identity snap function"). // // 2. "snap_radius", the maximum distance that vertices can move when // snapped. The snap_radius must be at least as large as the maximum // distance between P and SnapPoint(P) for any point P. // // Note that the maximum distance that edge interiors can move when // snapped is slightly larger than "snap_radius", and is returned by the // function S2Builder::Options::max_edge_deviation() (see there for // details). // // 3. "min_vertex_separation", the guaranteed minimum distance between // vertices in the output. This is generally a fraction of // "snap_radius" where the fraction depends on the snap function. // // 4. "min_edge_vertex_separation", the guaranteed minimum distance between // edges and non-incident vertices in the output. This is generally a // fraction of "snap_radius" where the fraction depends on the snap // function. // // It is important to note that SnapPoint() does not define the actual // mapping from input vertices to output vertices, since the points it // returns (the candidate snap sites) are further filtered to ensure that // they are separated by at least the snap radius. For example, if you // specify E7 coordinates (2cm resolution) and a snap radius of 10m, then a // subset of points returned by SnapPoint will be chosen (the "snap sites"), // and each input vertex will be mapped to the closest site. Therefore you // cannot assume that P is necessarily snapped to SnapPoint(P). // // S2Builder makes the following guarantees: // // 1. Every vertex is at a location returned by SnapPoint(). // // 2. Vertices are within "snap_radius" of the corresponding input vertex. // // 3. Edges are within "max_edge_deviation" of the corresponding input edge // (a distance slightly larger than "snap_radius"). // // 4. Vertices are separated by at least "min_vertex_separation" // (a fraction of "snap_radius" that depends on the snap function). // // 5. Edges and non-incident vertices are separated by at least // "min_edge_vertex_separation" (a fraction of "snap_radius"). // // 6. Vertex and edge locations do not change unless one of the conditions // above is not already met (idempotency / stability). // // 7. The topology of the input geometry is preserved (up to the creation // of degeneracies). This means that there exists a continuous // deformation from the input to the output such that no vertex // crosses an edge. class SnapFunction { public: virtual ~SnapFunction() = default; // The maximum distance that vertices can move when snapped. The snap // radius can be any value between zero and SnapFunction::kMaxSnapRadius(). // // If the snap radius is zero, then vertices are snapped together only if // they are identical. Edges will not be snapped to any vertices other // than their endpoints, even if there are vertices whose distance to the // edge is zero, unless split_crossing_edges() is true (see below). // // REQUIRES: snap_radius() <= kMaxSnapRadius virtual S1Angle snap_radius() const = 0; // The maximum supported snap radius (equivalent to about 7800km). static S1Angle kMaxSnapRadius(); // The guaranteed minimum distance between vertices in the output. // This is generally some fraction of "snap_radius". virtual S1Angle min_vertex_separation() const = 0; // The guaranteed minimum spacing between edges and non-incident vertices // in the output. This is generally some fraction of "snap_radius". virtual S1Angle min_edge_vertex_separation() const = 0; // Returns a candidate snap site for the given point. The final vertex // locations are a subset of the snap sites returned by this function // (spaced at least "min_vertex_separation" apart). // // The only requirement is that SnapPoint(x) must return a point whose // distance from "x" is no greater than "snap_radius". virtual S2Point SnapPoint(const S2Point& point) const = 0; // Returns a deep copy of this SnapFunction. virtual std::unique_ptr Clone() const = 0; }; class Options { public: Options(); // Convenience constructor that calls set_snap_function(). explicit Options(const SnapFunction& snap_function); // Sets the desired snap function. The snap function is copied // internally, so you can safely pass a temporary object. // // Note that if your input data includes vertices that were created using // S2::GetIntersection(), then you should use a "snap_radius" of // at least S2::kIntersectionMergeRadius, e.g. by calling // // options.set_snap_function(s2builderutil::IdentitySnapFunction( // S2::kIntersectionMergeRadius)); // // DEFAULT: s2builderutil::IdentitySnapFunction(S1Angle::Zero()) // [This does no snapping and preserves all input vertices exactly.] const SnapFunction& snap_function() const; void set_snap_function(const SnapFunction& snap_function); // The maximum distance from snapped edge vertices to the original edge. // This is the same as snap_function().snap_radius() except when // split_crossing_edges() is true (see below), in which case the edge snap // radius is increased by S2::kIntersectionError. S1Angle edge_snap_radius() const; // The maximum distance that any point along an edge can move when snapped. // It is slightly larger than edge_snap_radius() because when a geodesic // edge is snapped, the edge center moves further than its endpoints. // S2Builder ensures that this distance is at most 10% larger than // edge_snap_radius(). S1Angle max_edge_deviation() const; // If true, then detect all pairs of crossing edges and eliminate them by // adding a new vertex at their intersection point. See also the // AddIntersection() method which allows intersection points to be added // selectively. // // When this option is true, intersection_tolerance() is automatically set // to a minimum of S2::kIntersectionError (see intersection_tolerance() // for why this is necessary). Note that this means that edges can move // by up to S2::kIntersectionError even when the specified snap radius is // zero. The exact distance that edges can move is always given by // max_edge_deviation() defined above. // // Undirected edges should always be used when the output is a polygon, // since splitting a directed loop at a self-intersection converts it into // two loops that don't define a consistent interior according to the // "interior is on the left" rule. (On the other hand, it is fine to use // directed edges when defining a polygon *mesh* because in that case the // input consists of sibling edge pairs.) // // Self-intersections can also arise when importing data from a 2D // projection. You can minimize this problem by subdividing the input // edges so that the S2 edges (which are geodesics) stay close to the // original projected edges (which are curves on the sphere). This can // be done using S2EdgeTessellator, for example. // // DEFAULT: false bool split_crossing_edges() const; void set_split_crossing_edges(bool split_crossing_edges); // Specifies the maximum allowable distance between a vertex added by // AddIntersection() and the edge(s) that it is intended to snap to. This // method must be called before AddIntersection() can be used. It has the // effect of increasing the snap radius for edges (but not vertices) by // the given distance. // // The intersection tolerance should be set to the maximum error in the // intersection calculation used. For example, if S2::GetIntersection() // is used then the error should be set to S2::kIntersectionError. If // S2::GetPointOnLine() is used then the error should be set to // S2::kGetPointOnLineError. If S2::Project() is used then the error // should be set to S2::kProjectPerpendicularError. If more than one // method is used then the intersection tolerance should be set to the // maximum such error. // // The reason this option is necessary is that computed intersection // points are not exact. For example, S2::GetIntersection(a, b, c, d) // returns a point up to S2::kIntersectionError away from the true // mathematical intersection of the edges AB and CD. Furthermore such // intersection points are subject to further snapping in order to ensure // that no pair of vertices is closer than the specified snap radius. For // example, suppose the computed intersection point X of edges AB and CD // is 1 nanonmeter away from both edges, and the snap radius is 1 meter. // In that case X might snap to another vertex Y exactly 1 meter away, // which would leave us with a vertex Y that could be up to 1.000000001 // meters from the edges AB and/or CD. This means that AB and/or CD might // not snap to Y leaving us with two edges that still cross each other. // // However if the intersection tolerance is set to 1 nanometer then the // snap radius for edges is increased to 1.000000001 meters ensuring that // both edges snap to a common vertex even in this worst case. (This // technique does not work if the vertex snap radius is increased as well; // it requires edges and vertices to be handled differently.) // // Note that this option allows edges to move by up to the given // intersection tolerance even when the snap radius is zero. The exact // distance that edges can move is always given by max_edge_deviation() // defined above. // // When split_crossing_edges() is true, the intersection tolerance is // automatically set to a minimum of S2::kIntersectionError. A larger // value can be specified by calling this method explicitly. // // DEFAULT: S1Angle::Zero() S1Angle intersection_tolerance() const; void set_intersection_tolerance(S1Angle intersection_tolerance); // If true, then simplify the output geometry by replacing nearly straight // chains of short edges with a single long edge. // // The combined effect of snapping and simplifying will not change the // input by more than the guaranteed tolerances (see the list documented // with the SnapFunction class). For example, simplified edges are // guaranteed to pass within snap_radius() of the *original* positions of // all vertices that were removed from that edge. This is a much tighter // guarantee than can be achieved by snapping and simplifying separately. // // However, note that this option does not guarantee idempotency. In // other words, simplifying geometry that has already been simplified once // may simplify it further. (This is unavoidable, since tolerances are // measured with respect to the original geometry, which is no longer // available when the geometry is simplified a second time.) // // When the output consists of multiple layers, simplification is // guaranteed to be consistent: for example, edge chains are simplified in // the same way across layers, and simplification preserves topological // relationships between layers (e.g., no crossing edges will be created). // Note that edge chains in different layers do not need to be identical // (or even have the same number of vertices, etc) in order to be // simplified together. All that is required is that they are close // enough together so that the same simplified edge can meet all of their // individual snapping guarantees. // // Note that edge chains are approximated as parametric curves rather than // point sets. This means that if an edge chain backtracks on itself (for // example, ABCDEFEDCDEFGH) then such backtracking will be preserved to // within snap_radius() (for example, if the preceding point were all in a // straight line then the edge chain would be simplified to ACFCFH, noting // that C and F have degree > 2 and therefore can't be simplified away). // // Simplified edges are assigned all labels associated with the edges of // the simplified chain. // // For this option to have any effect, a SnapFunction with a non-zero // snap_radius() must be specified. Also note that vertices specified // using ForceVertex are never simplified away. // // DEFAULT: false bool simplify_edge_chains() const; void set_simplify_edge_chains(bool simplify_edge_chains); // If true, then snapping occurs only when the input geometry does not // already meet the S2Builder output guarantees (see the SnapFunction // class description for details). This means that if all input vertices // are at snapped locations, all vertex pairs are separated by at least // min_vertex_separation(), and all edge-vertex pairs are separated by at // least min_edge_vertex_separation(), then no snapping is done. // // If false, then all vertex pairs and edge-vertex pairs closer than // "snap_radius" will be considered for snapping. This can be useful, for // example, if you know that your geometry contains errors and you want to // make sure that features closer together than "snap_radius" are merged. // // This option is automatically turned off by simplify_edge_chains(), // since simplifying edge chains is never guaranteed to be idempotent. // // DEFAULT: true bool idempotent() const; void set_idempotent(bool idempotent); // Specifies that internal memory usage should be tracked using the given // S2MemoryTracker. If a memory limit is specified and more more memory // than this is required then an error will be returned. Example usage: // // S2MemoryTracker tracker; // tracker.set_limit(500 << 20); // 500 MB // S2Builder::Options options; // options.set_memory_tracker(&tracker); // S2Builder builder{options}; // ... // S2Error error; // if (!builder.Build(&error)) { // if (error.code() == S2Error::RESOURCE_EXHAUSTED) { // ABSL_LOG(ERROR) << error; // Memory limit exceeded // } // } // // CAVEATS: // // - Memory allocated by the output S2Builder layers is not tracked. // // - While memory tracking is reasonably complete and accurate, it does // not account for every last byte. It is intended only for the // purpose of preventing clients from running out of memory. // // DEFAULT: nullptr (memory tracking disabled) S2MemoryTracker* memory_tracker() const; void set_memory_tracker(S2MemoryTracker* tracker); // Options may be assigned and copied. Options(const Options& options); Options& operator=(const Options& options); private: std::unique_ptr snap_function_; bool split_crossing_edges_ = false; S1Angle intersection_tolerance_ = S1Angle::Zero(); bool simplify_edge_chains_ = false; bool idempotent_ = true; S2MemoryTracker* memory_tracker_ = nullptr; }; class Graph; // The following classes are only needed by Layer implementations. class GraphOptions; // For output layers that represent polygons, there is an ambiguity inherent // in spherical geometry that does not exist in planar geometry. Namely, if // a polygon has no edges, does it represent the empty polygon (containing // no points) or the full polygon (containing all points)? This ambiguity // also occurs for polygons that consist only of degeneracies, e.g. a // degenerate loop with only two edges could be either a degenerate shell in // the empty polygon or a degenerate hole in the full polygon. // // To resolve this ambiguity, an IsFullPolygonPredicate may be specified for // each output layer (see AddIsFullPolygonPredicate below). If the output // after snapping consists only of degenerate edges and/or sibling pairs // (including the case where there are no edges at all), then the layer // implementation calls the given predicate to determine whether the polygon // is empty or full except for those degeneracies. The predicate is given // an S2Builder::Graph containing the output edges, but note that in general // the predicate must also have knowledge of the input geometry in order to // determine the correct result. // // This predicate is only needed by layers that are assembled into polygons. // It is not used by other layer types. using IsFullPolygonPredicate = std::function; // Default constructor; requires Init() to be called. S2Builder(); // Convenience constructor that calls Init(). Note that to use the default // options, C++ syntax requires an extra layer of parentheses: // // S2Builder builder{S2Builder::Options()}; explicit S2Builder(const Options& options); // Initializes an S2Builder with the given options. void Init(const Options& options); const Options& options() const { return options_; } // Starts a new output layer. This method must be called before adding any // edges to the S2Builder. You may call this method multiple times to build // multiple geometric objects that are snapped to the same set of sites. // // For example, if you have a set of contour lines, then you could put each // contour line in a separate layer. This keeps the contour lines separate // from each other, while also ensuring that no crossing edges are created // when they are snapped and/or simplified. (This is not true if the // contour lines are snapped or simplified independently.) // // Similarly, if you have a set of polygons that share common boundaries // (e.g., countries), you can snap and/or simplify them at the same time by // putting them in different layers, while ensuring that their boundaries // remain consistent (i.e., no crossing edges or T-vertices are introduced). // // Ownership of the layer is transferred to the S2Builder. Example usage: // // S2Polyline line1, line2; // builder.StartLayer(make_unique(&line1))); // ... Add edges using builder.AddEdge(), etc ... // builder.StartLayer(make_unique(&line2))); // ... Add edges using builder.AddEdge(), etc ... // S2Error error; // ABSL_CHECK(builder.Build(&error)) << error; // Builds "line1" & "line2" class Layer; void StartLayer(std::unique_ptr layer); // Adds a degenerate edge (representing a point) to the current layer. void AddPoint(const S2Point& v); // Adds the given edge to the current layer. void AddEdge(const S2Point& v0, const S2Point& v1); // Adds the edges in the given polyline to the current layer. Note that // polylines with 0 or 1 vertices are defined to have no edges. void AddPolyline(S2PointSpan polyline); void AddPolyline(const S2Polyline& polyline); // Adds the edges in the given loop to the current layer. Note that a loop // consisting of one vertex adds a single degenerate edge. void AddLoop(S2PointLoopSpan loop); // Adds the edges in the given loop to the current layer. Loops with a single // vertex are ignored. // // If the sign() of an S2Loop is negative (i.e. the loop represents a hole // within a polygon), the edge directions are automatically reversed to // ensure that the polygon interior is always to the left of every edge. void AddLoop(const S2Loop& loop); // Adds the loops in the given polygon to the current layer. Loops // representing holes have their edge directions automatically reversed as // described for AddLoop(). Note that this method does not distinguish // between the empty and full polygons, i.e. adding a full polygon has the // same effect as adding an empty one. void AddPolygon(const S2Polygon& polygon); // Adds the edges of the given shape to the current layer. void AddShape(const S2Shape& shape); // If "vertex" is the intersection point of two edges AB and CD (as computed // by S2::GetIntersection()), this method ensures that AB and CD snap to a // common vertex. (Note that the common vertex may be different than // "vertex" in order to ensure that no pair of vertices is closer than the // given snap radius.) Unlike Options::split_crossing_edges(), this method // may be used to split crossing edge pairs selectively. // // This method can also be used to tessellate edges using S2::GetPointOnLine() // or S2::Project() provided that a suitable intersection tolerance is // specified (see intersection_tolerance() for details). // // This method implicitly overrides the idempotent() option, since adding an // intersection point implies a desire to have nearby edges snapped to it // even if these edges already satisfy the S2Builder output guarantees. // (Otherwise for example edges would never be snapped to nearby // intersection points when the snap radius is zero.) // // Note that unlike ForceVertex(), this method maintains all S2Builder // guarantees regarding minimum vertex-vertex separation, minimum // edge-vertex separation, and edge chain simplification. // // REQUIRES: options().intersection_tolerance() > S1Angle::Zero() // REQUIRES: "vertex" was computed by S2::GetIntersection() (in order to // guarantee that both edges snap to a common vertex) void AddIntersection(const S2Point& vertex); // For layers that are assembled into polygons, this method specifies a // predicate that is called when the output consists entirely of degenerate // edges and/or sibling pairs. The predicate is given an S2Builder::Graph // containing the output edges (if any) and is responsible for deciding // whether this graph represents the empty polygon (possibly with degenerate // shells) or the full polygon (possibly with degenerate holes). Note that // this cannot be determined from the output edges alone; it also requires // knowledge of the input geometry. (Also see IsFullPolygonPredicate above.) // // This method should be called at most once per layer; additional calls // simply overwrite the previous value for the current layer. // // The default predicate simply returns false (i.e., degenerate polygons are // assumed to be empty). Arguably it would better to return an error in // this case, but the fact is that relatively few clients need to be able to // construct full polygons, and it is unreasonable to expect all such // clients to supply an appropriate predicate. // // The reason for having a predicate rather than a boolean value is that the // predicate is responsible for determining whether the output polygon is // empty or full. In general the input geometry is not degenerate, but // rather collapses into a degenerate configuration due to snapping and/or // simplification. // // TODO(ericv): Provide standard predicates to handle common cases, // e.g. valid input geometry that becomes degenerate due to snapping. void AddIsFullPolygonPredicate(IsFullPolygonPredicate predicate); // A predicate that returns an error indicating that no polygon predicate // has been specified. static bool IsFullPolygonUnspecified(const S2Builder::Graph& g, S2Error* absl_nonnull error); // Returns a predicate that returns a constant value (true or false); static IsFullPolygonPredicate IsFullPolygon(bool is_full); // Forces a vertex to be located at the given position. This can be used to // prevent certain input vertices from moving. However if you are trying to // preserve input edges, be aware that this option does not prevent edges from // being split by new vertices. // // Forced vertices are subject to the following limitations: // // - Forced vertices are never snapped. This is true even when the given // position is not allowed by the given snap function (e.g. you can force // a vertex at a non-S2CellId center when using S2CellIdSnapFunction). // If you want to ensure that forced vertices obey the snap function // restrictions, you must call snap_function().SnapPoint() explicitly. // // - There is no guaranteed minimum separation between pairs of forced // vertices, i.e. snap_function().min_vertex_separation() does not apply. // (This must be true because forced vertices can be placed arbitrarily.) // // - There is no guaranteed minimum separation between forced vertices and // non-incident edges, i.e. snap_function().min_edge_vertex_separation() // does not apply. // // - Forced vertices are never simplified away (i.e. when simplification is // requested using options().simplify_edge_chains()). // // All other guarantees continue to hold, e.g. the input topology will always // be preserved. void ForceVertex(const S2Point& vertex); // Every edge can have a set of non-negative integer labels attached to it. // When used with an appropriate layer type, you can then retrieve the // labels associated with each output edge. This can be useful when merging // or combining data from several sources. (Note that in many cases it is // easier to use separate output layers rather than labels.) // // Labels are 32-bit non-negative integers. To support other label types, // you can use ValueLexicon to store the set of unique labels seen so far: // // ValueLexicon my_label_lexicon; // builder.set_label(my_label_lexicon.Add(label)); // // The current set of labels is represented as a stack. This makes it easy // to add and remove labels hierarchically (e.g., polygon 5, loop 2). Use // set_label() and clear_labels() if you need at most one label per edge. // using Label = int32_t; // Clear the stack of labels. void clear_labels(); // Add a label to the stack. // REQUIRES: label >= 0. void push_label(Label label); // Remove a label from the stack. void pop_label(); // Convenience function that clears the stack and adds a single label. // REQUIRES: label >= 0. void set_label(Label label); // Performs the requested edge splitting, snapping, simplification, etc, and // then assembles the resulting edges into the requested output layers. // // Returns true if all edges were assembled; otherwise sets "error" // appropriately. Depending on the error, some or all output layers may // have been created. Automatically resets the S2Builder state so that it // can be reused. // // REQUIRES: error != nullptr. bool Build(S2Error* absl_nonnull error); // Clears all input data and resets the builder state. Any options // specified are preserved. void Reset(); /////////////////////////////////////////////////////////////////////////// // The following methods may be called at any time, including from // S2Builder::Layer implementations. // Returns the number of input edges. int num_input_edges() const; // Returns the endpoints of the given input edge. // // REQUIRES: 0 <= input_edge_id < num_input_edges() S2Shape::Edge input_edge(int input_edge_id) const; private: ////////////////////// Input Types ///////////////////////// // All types associated with the S2Builder inputs are prefixed with "Input". // Identifies an input vertex. using InputVertexId = int32_t; // Defines an input edge. using InputEdge = std::pair; // Identifies an input edge. using InputEdgeId = int32_t; // Identifies the set of input edge ids that were snapped to a given edge. using InputEdgeIdSetId = int32_t; // Sort key for prioritizing input vertices. (Note that keys are *not* // compared using std::less; see SortInputVertices for details.) using InputVertexKey = std::pair; ////////////////////// Output Types ///////////////////////// // These types define the output vertices and edges. // Identifies a snapped vertex ("snap site"). If there is only one layer, // than SiteId is the same as Graph::VertexId, but if there are many layers // then each Graph may contain only a subset of the sites. Also see // GraphOptions::allow_vertex_filtering(). using SiteId = int32_t; // Defines an output edge. using Edge = std::pair; // Identifies an output edge. using EdgeId = int32_t; // Identifies an output edge in a particular layer. using LayerEdgeId = std::pair; ////////////////////// Internal Types ///////////////////////// class EdgeChainSimplifier; // MemoryTracker is a helper class to measure S2Builder memory usage. It is // based on a detailed analysis of the data structures used. This approach // is fragile because the memory tracking code needs to be updated whenever // S2Builder is modified, however S2Builder has been quite stable and this // approach allows the memory usage to be measured quite accurately. // // CAVEATS: // // - Does not track memory used by edge labels. (It is tricky to do this // accurately because they are stored in an IdSetLexicon, and labels // are typically a tiny fraction of the total space used.) // // - Does not track memory used to represent layers internally. (The // number of layers is typically small compared to the numbers of // vertices and edges, and the amount of memory used by the Layer and // IsFullPolygonPredicate objects is difficult to measure.) // // - Does not track memory used by the output layer Build() methods. (This // includes both temporary space, e.g. due to calling S2Builder::Graph // methods, and also any geometric objects created by these layers.) class MemoryTracker : public S2MemoryTracker::Client { public: bool TallyEdgeSites(const gtl::compact_array& sites); bool ReserveEdgeSite(gtl::compact_array* sites); bool ClearEdgeSites(std::vector>* edge_sites); bool TallyIndexedSite(); bool FixSiteIndexTally(const S2PointIndex& index); bool DoneSiteIndex(const S2PointIndex& index); bool TallySimplifyEdgeChains( absl::Span> site_vertices, absl::Span> layer_edges); bool TallyFilterVertices(int num_sites, absl::Span> layer_edges); bool DoneFilterVertices(); private: // The amount of non-inline memory used to store edge sites. int64_t edge_sites_bytes_ = 0; // The amount of memory used by the S2PointIndex for sites. int64_t site_index_bytes_ = 0; // The amount of temporary memory used by Graph::FilterVertices(). int64_t filter_vertices_bytes_ = 0; }; InputVertexId AddVertex(const S2Point& v); void ChooseSites(); void ChooseAllVerticesAsSites(); std::vector SortInputVertices(); void AddEdgeCrossings(const MutableS2ShapeIndex& input_edge_index); void AddForcedSites(S2PointIndex* site_index); bool is_forced(SiteId v) const; void ChooseInitialSites(S2PointIndex* site_index); S2Point SnapSite(const S2Point& point) const; void CollectSiteEdges(const S2PointIndex& site_index); void SortSitesByDistance(const S2Point& x, gtl::compact_array* sites) const; void InsertSiteByDistance(SiteId new_site_id, const S2Point& x, gtl::compact_array* sites); void AddExtraSites(const MutableS2ShapeIndex& input_edge_index); void MaybeAddExtraSites(InputEdgeId edge_id, absl::Span chain, const MutableS2ShapeIndex& input_edge_index, absl::flat_hash_set* edges_to_resnap); void AddExtraSite(const S2Point& new_site, const MutableS2ShapeIndex& input_edge_index, absl::flat_hash_set* edges_to_resnap); S2Point GetSeparationSite(const S2Point& site_to_avoid, const S2Point& v0, const S2Point& v1, InputEdgeId input_edge_id) const; S2Point GetCoverageEndpoint(const S2Point& p, const S2Point& n) const; void SnapEdge(InputEdgeId e, std::vector* chain) const; void BuildLayers(); void BuildLayerEdges( std::vector>* layer_edges, std::vector>* layer_input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon); void AddSnappedEdges( InputEdgeId begin, InputEdgeId end, const GraphOptions& options, std::vector* edges, std::vector* input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon, std::vector>* site_vertices); void MaybeAddInputVertex( InputVertexId v, SiteId id, std::vector>* site_vertices) const; void AddSnappedEdge(SiteId src, SiteId dst, InputEdgeIdSetId id, EdgeType edge_type, std::vector* edges, std::vector* input_edge_ids) const; void SimplifyEdgeChains( const std::vector>& site_vertices, std::vector>* layer_edges, std::vector>* layer_input_edge_ids, IdSetLexicon* input_edge_id_set_lexicon); void MergeLayerEdges( absl::Span> layer_edges, absl::Span> layer_input_edge_ids, std::vector* edges, std::vector* input_edge_ids, std::vector* edge_layers) const; static bool StableLessThan(const Edge& a, const Edge& b, const LayerEdgeId& ai, const LayerEdgeId& bi); //////////// Parameters ///////////// // S2Builder options. Options options_; // The maximum distance (inclusive) that a vertex can move when snapped, // equal to S1ChordAngle(options_.snap_function().snap_radius()). S1ChordAngle site_snap_radius_ca_; // The maximum distance (inclusive) that an edge can move when snapping to a // snap site. It can be slightly larger than the site snap radius when // edges are being split at crossings. S1ChordAngle edge_snap_radius_ca_; // True if we need to check that snapping has not changed the input topology // around any vertex (i.e. Voronoi site). Normally this is only necessary for // forced vertices, but if the snap radius is very small (e.g., zero) and // split_crossing_edges() is true then we need to do this for all vertices. // In all other situations, any snapped edge that crosses a vertex will also // be closer than min_edge_vertex_separation() to that vertex, which will // cause us to add a separation site anyway. bool check_all_site_crossings_; S1Angle max_edge_deviation_; S1ChordAngle edge_site_query_radius_ca_; S1ChordAngle min_edge_length_to_split_ca_; S1Angle min_site_separation_; S1ChordAngle min_site_separation_ca_; S1ChordAngle min_edge_site_separation_ca_; S1ChordAngle min_edge_site_separation_ca_limit_; S1ChordAngle max_adjacent_site_separation_ca_; // The squared sine of the edge snap radius. This is equivalent to the snap // radius (squared) for distances measured through the interior of the // sphere to the plane containing an edge. This value is used only when // interpolating new points along edges (see GetSeparationSite). double edge_snap_radius_sin2_; // A copy of the argument to Build(). S2Error* absl_nonnull error_; // True if snapping was requested. This is true if either snap_radius() is // positive, or split_crossing_edges() is true (which implicitly requests // snapping to ensure that both crossing edges are snapped to the // intersection point). bool snapping_requested_; // Initially false, and set to true when it is discovered that at least one // input vertex or edge does not meet the output guarantees (e.g., that // vertices are separated by at least snap_function.min_vertex_separation). bool snapping_needed_; //////////// Input Data ///////////// // A flag indicating whether label_set_ has been modified since the last // time label_set_id_ was computed. bool label_set_modified_; std::vector input_vertices_; std::vector input_edges_; std::vector> layers_; std::vector layer_options_; std::vector layer_begins_; std::vector layer_is_full_polygon_predicates_; // Each input edge has "label set id" (an int32_t) representing the set of // labels attached to that edge. This vector is populated only if at least // one label is used. using LabelSetId = int32_t; std::vector label_set_ids_; IdSetLexicon label_set_lexicon_; // The current set of labels (represented as a stack). std::vector::template rebind_alloc; public: typedef T value_type; typedef A allocator_type; typedef value_type* pointer; typedef const value_type* const_pointer; typedef value_type& reference; typedef const value_type& const_reference; typedef uint32_t size_type; typedef ptrdiff_t difference_type; typedef value_type* iterator; typedef const value_type* const_iterator; typedef std::reverse_iterator reverse_iterator; typedef std::reverse_iterator const_reverse_iterator; // Init() replace the default constructors; so it can be used in "union". // This means Init() must be called for every new compact_array_base void Init() noexcept { memset(this, 0, sizeof(*this)); } // Construct an array of size n and initialize the values to v. // Any old contents, if heap-allocated, will be leaked. void Construct(size_type n, const value_type& v = value_type()) { Init(); value_init(n, v); } // See 23.1.1/9 in the C++ standard for an explanation. template void Copy(Iterator first, Iterator last) { Init(); typedef typename std::is_integral::type Int; initialize(first, last, Int()); } void CopyFrom(const compact_array_base& v) { Init(); initialize(v.begin(), v.end(), std::false_type()); } compact_array_base& AssignFrom(const compact_array_base& v) { // Safe for self-assignment, which is rare. // Optimized to use existing allocated space. // Also to use assignment instead of copying where possible. if (size() < v.size()) { // grow reserve(v.size()); std::copy(v.begin(), v.begin() + size(), begin()); insert(end(), v.begin() + size(), v.end()); } else { // maybe shrink erase(begin() + v.size(), end()); std::copy(v.begin(), v.end(), begin()); } return *this; } // Deallocate the whole array. void Destruct() { if (!MayBeInlined() || Array() != InlinedSpace()) { value_allocator_type allocator; allocator.deallocate(Array(), capacity()); } Init(); } // Safe against self-swapping. // copying/destruction of compact_array_base is fairly trivial as the type // was designed to be usable in a C++98 union. void swap(compact_array_base& v) noexcept { compact_array_base tmp = *this; *this = v; v = tmp; } // The number of active items in the array. size_type size() const { return size_; } bool empty() const { return size() == 0; } // Maximum size that this data structure can hold. static constexpr size_type max_size() { return kMaxSize; } static constexpr bool MayBeInlined() { return kInlined > 0; } public: // Container interface (tables 65,66). iterator begin() { return Array(); } iterator end() { return Array() + size(); } const_iterator begin() const { return ConstArray(); } const_iterator end() const { return ConstArray() + size(); } reverse_iterator rbegin() { return reverse_iterator(end()); } reverse_iterator rend() { return reverse_iterator(Array()); } const_reverse_iterator rbegin() const { return const_reverse_iterator(end()); } const_reverse_iterator rend() const { return const_reverse_iterator(ConstArray()); } private: // This Insert() is private because it might return the end(). iterator Insert(const_iterator p, const value_type& v) { if (ABSL_PREDICT_FALSE(size() >= kMaxSize)) { absl::ThrowStdLengthError("compact_array size exceeded"); } iterator r = make_hole(p, 1); *r = v; return r; } public: // Sequence operations, table 67. iterator insert(const_iterator p, const value_type& v) { return Insert(p, v); } void insert(const_iterator p, size_type n, const value_type& v) { if (ABSL_PREDICT_FALSE(n > kMaxSize - size())) { absl::ThrowStdLengthError("compact_array size exceeded"); } value_insert(p, n, v); } // See 23.1.1/9 in the C++ standard for an explanation. template void insert(const_iterator p, Iterator first, Iterator last) { typedef typename std::is_integral::type Int; insert(p, first, last, Int()); } template reference emplace_back(Args&&... args) { return *Insert(end(), value_type(std::forward(args)...)); } template iterator emplace(const_iterator p, Args&&... args) { return Insert(p, value_type(std::forward(args)...)); } iterator erase(const_iterator p) { size_type index = p - begin(); erase_aux(p, 1); return begin() + index; } iterator erase(const_iterator first, const_iterator last) { size_type index = first - begin(); erase_aux(first, last - first); return begin() + index; } // clear just resets the size to 0, without deallocating the storage. // To deallocate the array, use Destruct(). void clear() { set_size(0); } reference front() { return begin()[0]; } const_reference front() const { return begin()[0]; } reference back() { return end()[-1]; } const_reference back() const { return end()[-1]; } void push_back(const value_type& v) { iterator p = make_hole(end(), 1); *p = v; } void pop_back() { erase_aux(end() - 1, 1); } reference operator[](size_type n) { ABSL_HARDENING_ASSERT(n < size_); return Array()[n]; } const_reference operator[](size_type n) const { ABSL_HARDENING_ASSERT(n < size_); return ConstArray()[n]; } reference at(size_type n) { if (ABSL_PREDICT_FALSE(n >= size_)) { absl::ThrowStdOutOfRange("compact_array_base::at"); } return Array()[n]; } const_reference at(size_type n) const { if (ABSL_PREDICT_FALSE(n >= size_)) { absl::ThrowStdOutOfRange("compact_array_base::at"); } return ConstArray()[n]; } // Preallocate the array of size n. Only changes the capacity, not size. void reserve(int n) { reallocate(n); } size_type capacity() const { return is_exponent_ ? (1 << capacity_) : capacity_; } void resize(size_type n) { if (n > capacity()) reserve(n); // resize(n) is the only place in the class that exposes uninitialized // memory as live elements, so call a constructor for each element if // needed. // Destroying elements on shrinking resize isn't a concern, since the // value_type must be trivially destructible. if (n > size() && !absl::is_trivially_default_constructible::value) { // Increasing size would expose unconstructed elements. value_type* new_end = Array() + n; for (value_type* p = Array() + size(); p != new_end; ++p) new (p) value_type(); } set_size(n); } template friend H AbslHashValue(H h, const compact_array_base& v) { return H::combine( H::combine_contiguous(std::move(h), v.ConstArray(), v.size()), v.size()); } private: // Low-level helper functions. void set_size(size_type n) { ABSL_DCHECK_LE(n, capacity()); size_ = n; } void set_capacity(size_type n) { ABSL_DCHECK_LE(size(), n); is_exponent_ = (n >= kExponentStart); capacity_ = is_exponent_ ? absl::bit_width(n - 1) : n; // A tiny optimization here would be to set capacity_ to kInlined if // it's currently less. We don't bother, because doing so would require // changing the existing comments and unittests that say that, for small n, // capacity() will be exactly n if one calls reserve(n). ABSL_DCHECK(n == capacity() || n > kInlined); } // Make capacity n or more. Reallocate and copy data as necessary. void reallocate(size_type n) { size_type old_capacity = capacity(); if (n <= old_capacity) return; size_type new_n = n; if (new_n > kInlined) { new_n = nallocx(n * sizeof(T), 0) / sizeof(T); } set_capacity(new_n); if constexpr (MayBeInlined()) { if (!IsInlined() && n <= kInlined) { SetInlined(); return; } else if (IsInlined()) { if (n > kInlined) { value_allocator_type allocator; value_type* new_array = allocator.allocate(capacity()); memcpy(new_array, InlinedSpace(), size() * sizeof(T)); SetArray(new_array); } return; } } value_allocator_type allocator; T* new_ptr = allocator.allocate(capacity()); if (old_capacity != 0) { memcpy(new_ptr, Array(), old_capacity * sizeof(T)); allocator.deallocate(Array(), old_capacity); } SetArray(new_ptr); } value_type* lastp() { return Array() + size(); } void move(const value_type* first, const value_type* last, value_type* out) { memmove(out, first, (last - first) * sizeof(value_type)); } iterator make_hole(const_iterator p, size_type n) { iterator q = const_cast(p); if (n != 0) { size_type new_size = size() + n; size_type index = q - Array(); reallocate(new_size); q = Array() + index; move(q, Array() + new_size - n, q + n); set_size(new_size); } return q; } void erase_aux(const_iterator p, size_type n) { iterator q = const_cast(p); size_type new_size = size() - n; move(q + n, lastp(), q); reallocate(new_size); set_size(new_size); } private: // Helper functions for range/value. void value_init(size_type n, const value_type& v) { reserve(n); set_size(n); std::fill(Array(), lastp(), v); } template void range_init(InputIter first, InputIter last, std::input_iterator_tag) { for (; first != last; ++first) push_back(*first); } template void range_init(ForwIter first, ForwIter last, std::forward_iterator_tag) { size_type n = std::distance(first, last); reserve(n); set_size(n); std::copy(first, last, Array()); } template void initialize(Integer n, Integer v, std::true_type) { value_init(n, v); } template void initialize(Iterator first, Iterator last, std::false_type) { typedef typename std::iterator_traits::iterator_category Cat; range_init(first, last, Cat()); } void value_insert(const_iterator p, size_type n, const value_type& v) { if (ABSL_PREDICT_FALSE(n > kMaxSize - size())) { absl::ThrowStdLengthError("compact_array size exceeded"); } iterator hole = make_hole(p, n); std::fill(hole, hole + n, v); } template void range_insert(const_iterator p, InputIter first, InputIter last, std::input_iterator_tag) { size_type pos = p - begin(); size_type old_size = size(); for (; first != last; ++first) push_back(*first); std::rotate(begin() + pos, begin() + old_size, end()); } template void range_insert(const_iterator p, ForwIter first, ForwIter last, std::forward_iterator_tag) { size_type n = std::distance(first, last); if (ABSL_PREDICT_FALSE(n > kMaxSize - size())) { absl::ThrowStdLengthError("compact_array size exceeded"); } std::copy(first, last, make_hole(p, n)); } template void insert(const_iterator p, Integer n, Integer v, std::true_type) { value_insert(p, n, v); } template void insert(const_iterator p, Iterator first, Iterator last, std::false_type) { typedef typename std::iterator_traits::iterator_category Cat; range_insert(p, first, last, Cat()); } static_assert(absl::is_trivially_copy_constructible::value && absl::is_trivially_copy_assignable::value && absl::is_trivially_destructible::value, "Requires trivial copy, assignment, and destructor."); }; // Allocates storage for constants in compact_array_base template const int compact_array_base::kSizeNumBits; template const int compact_array_base::kCapacityNumBits; template const int compact_array_base::kMaxSize; template const int compact_array_base::kExponentStart; // compact_array: Wrapper for compact_array_base that provides the // constructors and destructor. template > class compact_array : public compact_array_base { private: typedef compact_array_base Base; public: typedef typename Base::value_type value_type; typedef typename Base::allocator_type allocator_type; typedef typename Base::pointer pointer; typedef typename Base::const_pointer const_pointer; typedef typename Base::reference reference; typedef typename Base::const_reference const_reference; typedef typename Base::size_type size_type; typedef typename Base::iterator iterator; typedef typename Base::const_iterator const_iterator; typedef typename Base::reverse_iterator reverse_iterator; typedef typename Base::const_reverse_iterator const_reverse_iterator; compact_array() noexcept(noexcept(std::declval().Init())) { Base::Init(); } explicit compact_array(size_type n) { Base::Construct(n, value_type()); } compact_array(size_type n, const value_type& v) { Base::Construct(n, v); } // See 23.1.1/9 in the C++ standard for an explanation. template compact_array(Iterator first, Iterator last) { Base::Copy(first, last); } compact_array(const compact_array& v) { Base::CopyFrom(v); } compact_array(compact_array&& v) noexcept( noexcept(compact_array()) && noexcept(std::declval().swap(v))) : compact_array() { Base::swap(v); } compact_array& operator=(const compact_array& v) { Base::AssignFrom(v); return *this; } compact_array& operator=(compact_array&& v) noexcept { // swap is only right here because the objects are trivially destructible // and thus there are no side effects on their destructor. // Otherwise we must destroy the objects on `this`. Base::swap(v); return *this; } ~compact_array() { Base::Destruct(); } }; // Comparison operators template bool operator==(const compact_array& x, const compact_array& y) { return x.size() == y.size() && std::equal(x.begin(), x.end(), y.begin()); } template bool operator!=(const compact_array& x, const compact_array& y) { return !(x == y); } template bool operator<(const compact_array& x, const compact_array& y) { return std::lexicographical_compare(x.begin(), x.end(), y.begin(), y.end()); } template bool operator>(const compact_array& x, const compact_array& y) { return y < x; } template bool operator<=(const compact_array& x, const compact_array& y) { return !(y < x); } template bool operator>=(const compact_array& x, const compact_array& y) { return !(x < y); } // Swap template inline void swap(compact_array& x, compact_array& y) noexcept { x.swap(y); } namespace compact_array_internal { struct LogArray : public gtl::LogLegacyUpTo100 { template void Log(std::ostream& out, const ElementT& element) const { // NOLINT out << element; } void Log(std::ostream& out, int8_t c) const { // NOLINT out << static_cast(c); } void Log(std::ostream& out, uint8_t c) const { // NOLINT out << static_cast(c); } void LogOpening(std::ostream& out) const { out << "["; } // NOLINT void LogClosing(std::ostream& out) const { out << "]"; } // NOLINT }; } // namespace compact_array_internal // Output operator for compact_array. Requires that T has an // operator<< for std::ostream. Note that // compact_array_internal::LogArray ensures that "signed char" and // "unsigned char" types print as integers. template std::ostream& operator<<(std::ostream& out, const compact_array& array) { gtl::LogRangeToStream(out, array.begin(), array.end(), compact_array_internal::LogArray()); return out; } } // namespace gtl #endif // S2_UTIL_GTL_COMPACT_ARRAY_H_ src/s2/util/gtl/container_logging.h000066400000000000000000000243201524103652300175770ustar00rootroot00000000000000// Copyright 2013 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // All Rights Reserved. // // Utilities for container logging. // TODO(user): Broaden the scope and rename to "stream_util.h" // // // The typical use looks like this: // // ABSL_LOG(INFO) << gtl::LogContainer(container); // // By default, LogContainer() uses the LogShortUpTo100 policy: comma-space // separation, no newlines, and with limit of 100 items. // // Policies can be specified: // // ABSL_LOG(INFO) << gtl::LogContainer(container, gtl::LogMultiline()); // // The above example will print the container using newlines between // elements, enclosed in [] braces. // // See below for further details on policies. #ifndef S2_UTIL_GTL_CONTAINER_LOGGING_H_ #define S2_UTIL_GTL_CONTAINER_LOGGING_H_ #include #include #include #include #include #include #include "absl/strings/str_cat.h" #include "s2/util/gtl/requires.h" namespace gtl { // Several policy classes below determine how LogRangeToStream will // format a range of items. A Policy class should have these methods: // // Called to print an individual container element. // void Log(ostream &out, const ElementT &element) const; // // Called before printing the set of elements: // void LogOpening(ostream &out) const; // // Called after printing the set of elements: // void LogClosing(ostream &out) const; // // Called before printing the first element: // void LogFirstSeparator(ostream &out) const; // // Called before printing the remaining elements: // void LogSeparator(ostream &out) const; // // Returns the maximum number of elements to print: // int64 MaxElements() const; // // Called to print an indication that MaximumElements() was reached: // void LogEllipsis(ostream &out) const; namespace internal { struct LogBase { template void Log(std::ostream &out, const ElementT &element) const { // NOLINT // Fallback to `AbslStringify` if the type does not have `operator<<`. if constexpr (Requires( [](auto &&x, auto &&y) -> decltype(x << y) {})) { out << element; } else { out << absl::StrCat(element); } } void LogEllipsis(std::ostream &out) const { // NOLINT out << "..."; } }; struct LogShortBase : public LogBase { void LogOpening(std::ostream &out) const { out << "["; } // NOLINT void LogClosing(std::ostream &out) const { out << "]"; } // NOLINT void LogFirstSeparator(std::ostream &out) const { out << ""; } // NOLINT void LogSeparator(std::ostream &out) const { out << ", "; } // NOLINT }; struct LogMultilineBase : public LogBase { void LogOpening(std::ostream &out) const { out << "["; } // NOLINT void LogClosing(std::ostream &out) const { out << "\n]"; } // NOLINT void LogFirstSeparator(std::ostream &out) const { out << "\n"; } // NOLINT void LogSeparator(std::ostream &out) const { out << "\n"; } // NOLINT }; struct LogLegacyBase : public LogBase { void LogOpening(std::ostream &out) const { out << ""; } // NOLINT void LogClosing(std::ostream &out) const { out << ""; } // NOLINT void LogFirstSeparator(std::ostream &out) const { out << ""; } // NOLINT void LogSeparator(std::ostream &out) const { out << " "; } // NOLINT }; } // namespace internal // LogShort uses [] braces and separates items with comma-spaces. For // example "[1, 2, 3]". struct LogShort : public internal::LogShortBase { int64_t MaxElements() const { return std::numeric_limits::max(); } }; // LogShortUpToN(max_elements) formats the same as LogShort but prints no more // than the max_elements elements. class LogShortUpToN : public internal::LogShortBase { public: explicit LogShortUpToN(int64_t max_elements) : max_elements_(max_elements) {} int64_t MaxElements() const { return max_elements_; } private: int64_t max_elements_; }; // LogShortUpTo100 formats the same as LogShort but prints no more // than 100 elements. struct LogShortUpTo100 : public LogShortUpToN { LogShortUpTo100() : LogShortUpToN(100) {} }; // LogMultiline uses [] braces and separates items with // newlines. For example "[ // 1 // 2 // 3 // ]". struct LogMultiline : public internal::LogMultilineBase { int64_t MaxElements() const { return std::numeric_limits::max(); } }; // LogMultilineUpToN(max_elements) formats the same as LogMultiline but // prints no more than max_elements elements. class LogMultilineUpToN : public internal::LogMultilineBase { public: explicit LogMultilineUpToN(int64_t max_elements) : max_elements_(max_elements) {} int64_t MaxElements() const { return max_elements_; } private: int64_t max_elements_; }; // LogMultilineUpTo100 formats the same as LogMultiline but // prints no more than 100 elements. struct LogMultilineUpTo100 : public LogMultilineUpToN { LogMultilineUpTo100() : LogMultilineUpToN(100) {} }; // The legacy behavior of LogSequence() does not use braces and // separates items with spaces. For example "1 2 3". struct LogLegacyUpTo100 : public internal::LogLegacyBase { int64_t MaxElements() const { return 100; } }; struct LogLegacy : public internal::LogLegacyBase { int64_t MaxElements() const { return std::numeric_limits::max(); } }; // The default policy for new code. typedef LogShortUpTo100 LogDefault; // LogRangeToStream should be used to define operator<< for // STL and STL-like containers. For example, see stl_logging.h. template inline void LogRangeToStream(std::ostream &out, // NOLINT IteratorT begin, IteratorT end, const PolicyT &policy) { policy.LogOpening(out); for (int64_t i = 0; begin != end && i < policy.MaxElements(); ++i, ++begin) { if (i == 0) { policy.LogFirstSeparator(out); } else { policy.LogSeparator(out); } policy.Log(out, *begin); } if (begin != end) { policy.LogSeparator(out); policy.LogEllipsis(out); } policy.LogClosing(out); } namespace detail { // RangeLogger is a helper class for gtl::LogRange and // gtl::LogContainer; do not use it directly. This object // captures iterators into the argument of the LogRange and // LogContainer functions, so its lifetime should be confined to a // single logging statement. Objects of this type should not be // assigned to local variables. template class RangeLogger { public: RangeLogger(const IteratorT &begin, const IteratorT &end, const PolicyT &policy) : begin_(begin), end_(end), policy_(policy) {} friend std::ostream &operator<<(std::ostream &out, const RangeLogger &range) { gtl::LogRangeToStream(out, range.begin_, range.end_, range.policy_); return out; } // operator<< above is generally recommended. However, some situations may // require a string, so a convenience str() method is provided as well. std::string str() const { std::stringstream ss; ss << *this; return ss.str(); } private: IteratorT begin_; IteratorT end_; PolicyT policy_; }; template class EnumLogger { public: explicit EnumLogger(E e) : e_(e) {} friend std::ostream &operator<<(std::ostream &out, const EnumLogger &v) { using I = typename std::underlying_type::type; return out << static_cast(v.e_); } private: E e_; }; } // namespace detail // Log a range using "policy". For example: // // ABSL_LOG(INFO) << gtl::LogRange(start_pos, end_pos, gtl::LogMultiline()); // // The above example will print the range using newlines between // elements, enclosed in [] braces. template detail::RangeLogger LogRange(const IteratorT &begin, const IteratorT &end, const PolicyT &policy) { return gtl::detail::RangeLogger(begin, end, policy); } // Log a range. For example: // // ABSL_LOG(INFO) << gtl::LogRange(start_pos, end_pos); // // By default, Range() uses the LogShortUpTo100 policy: comma-space // separation, no newlines, and with limit of 100 items. template detail::RangeLogger LogRange(const IteratorT &begin, const IteratorT &end) { return gtl::LogRange(begin, end, LogDefault()); } // Log a container using "policy". For example: // // ABSL_LOG(INFO) << gtl::LogContainer(container, gtl::LogMultiline()); // // The above example will print the container using newlines between // elements, enclosed in [] braces. template auto LogContainer(const ContainerT &container, const PolicyT &policy) -> decltype(gtl::LogRange(container.begin(), container.end(), policy)) { return gtl::LogRange(container.begin(), container.end(), policy); } // Log a container. For example: // // ABSL_LOG(INFO) << gtl::LogContainer(container); // // By default, Container() uses the LogShortUpTo100 policy: comma-space // separation, no newlines, and with limit of 100 items. template auto LogContainer(const ContainerT &container) -> decltype(gtl::LogContainer(container, LogDefault())) { return gtl::LogContainer(container, LogDefault()); } // Log a (possibly scoped) enum. For example: // // enum class Color { kRed, kGreen, kBlue }; // ABSL_LOG(INFO) << gtl::LogEnum(kRed); template detail::EnumLogger LogEnum(E e) { static_assert(std::is_enum::value, "must be an enum"); return detail::EnumLogger(e); } } // namespace gtl #endif // S2_UTIL_GTL_CONTAINER_LOGGING_H_ src/s2/util/gtl/dense_hash_set.h000066400000000000000000000321741524103652300170710ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // --- // // This is just a very thin wrapper over densehashtable.h, just // like sgi stl's stl_hash_set is a very thin wrapper over // stl_hashtable. // // This is more different from dense_hash_map than you might think, // because all iterators for sets are const (you obviously can't // change the key, and for sets there is no value). // // NOTE: this is exactly like sparse_hash_set.h, with the word // "sparse" replaced by "dense", except for the addition of // set_empty_key(). // // YOU MUST CALL SET_EMPTY_KEY() IMMEDIATELY AFTER CONSTRUCTION. // // Otherwise your program will die in mysterious ways. (Note if you // use the constructor that takes an InputIterator range, you pass in // the empty key in the constructor, rather than after. As a result, // this constructor differs from the standard STL version.) // // In other respects, we adhere mostly to the STL semantics for // hash-map. One important exception is that insert() may invalidate // iterators entirely -- STL semantics are that insert() may reorder // iterators, but they all still refer to something valid in the // hashtable. Not so for us. Likewise, insert() may invalidate // pointers into the hashtable. (Whether insert invalidates iterators // and pointers depends on whether it results in a hashtable resize, // but that's an implementation detail that may change in the future.) // On the plus side, delete() doesn't invalidate iterators or pointers // at all, or even change the ordering of elements. // // Also please note: // // 1) set_deleted_key(): // If you want to use erase() you must call set_deleted_key(), // in addition to set_empty_key(), after construction. // The deleted and empty keys must differ. // // 2) Keys equal to the empty key or deleted key (if any) cannot be // used as keys for find(), count(), insert(), etc. // // 3) min_load_factor(): // Setting the minimum load factor controls how aggressively the // table is shrunk when keys are erased. Setting it to 0.0 // guarantees that the hash table will never shrink. // // 4) resize(0): // When an item is deleted, its memory isn't freed right // away. This allows you to iterate over a hashtable, // and call erase(), without invalidating the iterator. // To force the memory to be freed, call resize(0). // For tr1 compatibility, this can also be called as rehash(0). // Roughly speaking: // (1) dense_hash_set: fastest, uses the most memory unless entries are small // (2) sparse_hash_set: slowest, uses the least memory // (3) hash_set / unordered_set (STL): in the middle // // Typically I use sparse_hash_set when I care about space and/or when // I need to save the hashtable on disk. I use hash_set otherwise. I // don't personally use dense_hash_set ever; some people use it for // small sets with lots of lookups. // // - dense_hash_set has, typically, about 78% memory overhead (if your // data takes up X bytes, the hash_set uses .78X more bytes in overhead). // - sparse_hash_set has about 4 bits overhead per entry. // - sparse_hash_set can be 3-7 times slower than the others for lookup and, // especially, inserts. See time_hash_map.cc for details. // // See /usr/(local/)?doc/sparsehash-*/dense_hash_set.html // for information about how to use this class. #ifndef S2_UTIL_GTL_DENSE_HASH_SET_H_ #define S2_UTIL_GTL_DENSE_HASH_SET_H_ #include #include #include #include #include #include #include "absl/base/macros.h" #include "s2/util/gtl/densehashtable.h" // IWYU pragma: export // Some files test for this symbol. #define S2__DENSE_HASH_SET_H_ namespace gtl { template , class EqualKey = std::equal_to, class Alloc = std::allocator> class dense_hash_set { private: // Apparently identity is not stl-standard, so we define our own struct Identity { typedef const Value& result_type; const Value& operator()(const Value& v) const { return v; } }; struct SetKey { void operator()(Value* value, const Value& new_key) const { *value = new_key; } }; // The actual data typedef dense_hashtable ht; ht rep; public: typedef typename ht::key_type key_type; typedef typename ht::value_type value_type; typedef typename ht::hasher hasher; typedef typename ht::key_equal key_equal; typedef Alloc allocator_type; typedef typename ht::size_type size_type; typedef typename ht::difference_type difference_type; typedef typename ht::const_pointer pointer; typedef typename ht::const_pointer const_pointer; typedef typename ht::const_reference reference; typedef typename ht::const_reference const_reference; typedef typename ht::const_iterator iterator; typedef typename ht::const_iterator const_iterator; typedef typename ht::const_local_iterator local_iterator; typedef typename ht::const_local_iterator const_local_iterator; // Iterator functions -- recall all iterators are const iterator begin() const { return rep.begin(); } iterator end() const { return rep.end(); } // These come from tr1's unordered_set. For us, a bucket has 0 or 1 elements. ABSL_DEPRECATED( "This method is slated for removal. Please migrate to " "absl::flat_hash_set.") local_iterator begin(size_type i) const { return rep.begin(i); } // Accessor functions allocator_type get_allocator() const { return rep.get_allocator(); } hasher hash_funct() const { return rep.hash_funct(); } hasher hash_function() const { return hash_funct(); } // tr1 name key_equal key_eq() const { return rep.key_eq(); } // Constructors dense_hash_set() = default; explicit dense_hash_set(size_type expected_max_items_in_table, const hasher& hf = hasher(), const key_equal& eql = key_equal(), const allocator_type& alloc = allocator_type()) : rep(expected_max_items_in_table, hf, eql, Identity(), SetKey(), alloc) { } template dense_hash_set(InputIterator f, InputIterator l, const key_type& empty_key_val, size_type expected_max_items_in_table = 0, const hasher& hf = hasher(), const key_equal& eql = key_equal(), const allocator_type& alloc = allocator_type()) : rep(expected_max_items_in_table, hf, eql, Identity(), SetKey(), alloc) { set_empty_key(empty_key_val); rep.insert(f, l); } // We use the default copy constructor // We use the default operator=() // We use the default destructor void clear() { rep.clear(); } // This clears the hash set without resizing it down to the minimum // bucket count, but rather keeps the number of buckets constant void clear_no_resize() { rep.clear_no_resize(); } void swap(dense_hash_set& hs) noexcept { rep.swap(hs.rep); } // Functions concerning size size_type size() const { return rep.size(); } size_type max_size() const { return rep.max_size(); } bool empty() const { return rep.empty(); } size_type bucket_count() const { return rep.bucket_count(); } float load_factor() const { return size() * 1.0f / bucket_count(); } float max_load_factor() const { float shrink, grow; rep.get_resizing_parameters(&shrink, &grow); return grow; } void max_load_factor(float new_grow) { float shrink, grow; rep.get_resizing_parameters(&shrink, &grow); rep.set_resizing_parameters(shrink, new_grow); } // These aren't tr1 methods but perhaps ought to be. ABSL_DEPRECATED( "This method is slated for removal. Please migrate to " "absl::flat_hash_set.") float min_load_factor() const { float shrink, grow; rep.get_resizing_parameters(&shrink, &grow); return shrink; } void min_load_factor(float new_shrink) { float shrink, grow; rep.get_resizing_parameters(&shrink, &grow); rep.set_resizing_parameters(new_shrink, grow); } // Deprecated; use min_load_factor() or max_load_factor() instead. void set_resizing_parameters(float shrink, float grow) { rep.set_resizing_parameters(shrink, grow); } void resize(size_type hint) { rep.resize(hint); } void rehash(size_type hint) { resize(hint); } // the tr1 name // Lookup routines iterator find(const key_type& key) const { return rep.find(key); } size_type count(const key_type& key) const { return rep.count(key); } std::pair equal_range(const key_type& key) const { return rep.equal_range(key); } // Insertion routines std::pair insert(const value_type& obj) { std::pair p = rep.insert(obj); return std::pair(p.first, p.second); // const to non-const } std::pair insert(value_type&& obj) { // NOLINT std::pair p = rep.insert(std::move(obj)); return std::pair(p.first, p.second); // const to non-const } template void insert(InputIterator f, InputIterator l) { rep.insert(f, l); } void insert(const_iterator f, const_iterator l) { rep.insert(f, l); } // Required for std::insert_iterator; the passed-in iterator is ignored. iterator insert(iterator, const value_type& obj) { return insert(obj).first; } iterator insert(iterator, value_type&& obj) { // NOLINT return insert(std::move(obj)).first; } // Unlike std::set, we cannot construct an element in place, as we do not have // a layer of indirection like std::set nodes. Therefore, emplace* methods do // not provide a performance advantage over insert + move. template std::pair emplace(Args&&... args) { return rep.insert(value_type(std::forward(args)...)); } // The passed-in const_iterator is ignored. template iterator emplace_hint(const_iterator, Args&&... args) { return rep.insert(value_type(std::forward(args)...)).first; } // Deletion and empty routines // THESE ARE NON-STANDARD! I make you specify an "impossible" key // value to identify deleted and empty buckets. You can change the // deleted key as time goes on, or get rid of it entirely to be insert-only. void set_empty_key(const key_type& key) { rep.set_empty_key(key); } void set_deleted_key(const key_type& key) { rep.set_deleted_key(key); } // These are standard size_type erase(const key_type& key) { return rep.erase(key); } void erase(iterator it) { rep.erase(it); } void erase(iterator f, iterator l) { rep.erase(f, l); } // Comparison bool operator==(const dense_hash_set& hs) const { return rep == hs.rep; } bool operator!=(const dense_hash_set& hs) const { return rep != hs.rep; } }; template inline void swap(dense_hash_set& hs1, dense_hash_set& hs2) noexcept { hs1.swap(hs2); } } #endif // S2_UTIL_GTL_DENSE_HASH_SET_H_ src/s2/util/gtl/densehashtable.h000066400000000000000000001606421524103652300170710ustar00rootroot00000000000000// Copyright 2005 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // --- // // A dense hashtable is a particular implementation of // a hashtable: one that is meant to minimize memory allocation. // It does this by using an array to store all the data. We // steal a value from the key space to indicate "empty" array // elements (ie indices where no item lives) and another to indicate // "deleted" elements. // // (Note it is possible to change the value of the delete key // on the fly; you can even remove it, though after that point // the hashtable is insert_only until you set it again. The empty // value however can't be changed.) // // To minimize allocation and pointer overhead, we use internal // probing, in which the hashtable is a single table, and collisions // are resolved by trying to insert again in another bucket. The // most cache-efficient internal probing schemes are linear probing // (which suffers, alas, from clumping) and quadratic probing, which // is what we implement by default. // // Type requirements: value_type is required to be Move Constructible // and Default Constructible. It is not required to be (and commonly // isn't) Assignable. // // You probably shouldn't use this code directly. Use dense_hash_map<> // or dense_hash_set<> instead. // You can change the following below: // HT_OCCUPANCY_PCT -- how full before we double size // HT_EMPTY_PCT -- how empty before we halve size // HT_MIN_BUCKETS -- default smallest bucket size // // You can also change enlarge_factor (which defaults to // HT_OCCUPANCY_PCT), and shrink_factor (which defaults to // HT_EMPTY_PCT) with set_resizing_parameters(). // // How to decide what values to use? // shrink_factor's default of .4 * OCCUPANCY_PCT, is probably good. // HT_MIN_BUCKETS is probably unnecessary since you can specify // (indirectly) the starting number of buckets at construct-time. // For enlarge_factor, you can use this chart to try to trade-off // expected lookup time to the space taken up. By default, this // code uses quadratic probing, though you can change it to linear // via JUMP_ below if you really want to. // // From // L = N / M, // where N is the number of data items in the table and M is the table size. // NUMBER OF PROBES / LOOKUP Successful Unsuccessful // Quadratic collision resolution 1 - ln(1-L) - L/2 1/(1-L) - L - ln(1-L) // Linear collision resolution [1+1/(1-L)]/2 [1+1/(1-L)^2]/2 // // -- enlarge_factor -- 0.10 0.50 0.60 0.75 0.80 0.90 0.99 // QUADRATIC COLLISION RES. // probes/successful lookup 1.05 1.44 1.62 2.01 2.21 2.85 5.11 // probes/unsuccessful lookup 1.11 2.19 2.82 4.64 5.81 11.4 103.6 // LINEAR COLLISION RES. // probes/successful lookup 1.06 1.5 1.75 2.5 3.0 5.5 50.5 // probes/unsuccessful lookup 1.12 2.5 3.6 8.5 13.0 50.0 5000.0 #ifndef S2_UTIL_GTL_DENSEHASHTABLE_H_ #define S2_UTIL_GTL_DENSEHASHTABLE_H_ #include // For swap(), eg #include #include #include #include // for FILE, fwrite, fread #include #include // For iterator tags #include // for numeric_limits #include // For uninitialized_fill #include #include #include #include #include #include "s2/util/gtl/hashtable_common.h" #include // For length_error namespace gtl { // Some files test for this symbol. #define S2__DENSEHASHTABLE_H_ // The probing method // Linear probing // #define JUMP_(key, num_probes) ( 1 ) // Quadratic probing #define JUMP_(key, num_probes) (num_probes) // The weird mod in the offset is entirely to quiet compiler warnings // as is the cast to int after doing the "x mod 256" #define PUT_(take_from, offset) \ do { \ if (putc(static_cast(offset >= sizeof(take_from) * 8) \ ? 0 \ : ((take_from) >> (offset)) % 256, \ fp) == EOF) \ return false; \ } while (0) #define GET_(add_to, offset) \ do { \ if ((x = getc(fp)) == EOF) \ return false; \ else if (offset >= sizeof(add_to) * 8) \ assert(x == 0); /* otherwise it's too big for us to represent */ \ else \ add_to |= \ (static_cast(x) << ((offset) % (sizeof(add_to) * 8))); \ } while (0) // Hashtable class, used to implement the hashed associative containers // hash_set and hash_map. // Value: what is stored in the table (each bucket is a Value). // Key: something in a 1-to-1 correspondence to a Value, that can be used // to search for a Value in the table (find() takes a Key). // HashFcn: Takes a Key and returns an integer, the more unique the better. // ExtractKey: given a Value, returns the unique Key associated with it. // Must have a result_type enum indicating the return type of // operator(). // SetKey: given a Value* and a Key, modifies the value such that // ExtractKey(value) == key. We guarantee this is only called // with key == deleted_key or key == empty_key. // EqualKey: Given two Keys, says whether they are the same (that is, // if they are both associated with the same Value). // Alloc: STL allocator to use to allocate memory. template class dense_hashtable; template struct dense_hashtable_const_iterator; // We're just an array, but we need to skip over empty and deleted elements template struct dense_hashtable_iterator { private: using value_alloc_type = typename std::allocator_traits::template rebind_alloc; using value_alloc_traits = typename std::allocator_traits::template rebind_traits; public: typedef dense_hashtable_iterator iterator; typedef dense_hashtable_const_iterator const_iterator; typedef std::forward_iterator_tag iterator_category; // very little defined! typedef V value_type; typedef typename value_alloc_traits::difference_type difference_type; typedef typename value_alloc_traits::size_type size_type; typedef typename value_alloc_traits::value_type& reference; typedef typename value_alloc_traits::pointer pointer; // "Real" constructor and default constructor dense_hashtable_iterator( const dense_hashtable* h, pointer it, pointer it_end, bool advance) : ht(h), pos(it), end(it_end) { if (advance) advance_past_empty_and_deleted(); } dense_hashtable_iterator() = default; // The default destructor is fine; we don't define one // The default operator= is fine; we don't define one // Happy dereferencer reference operator*() const { return *pos; } pointer operator->() const { return &(operator*()); } // Arithmetic. The only hard part is making sure that // we're not on an empty or marked-deleted array element void advance_past_empty_and_deleted() { while (pos != end && (ht->test_empty(*this) || ht->test_deleted(*this))) ++pos; } iterator& operator++() { assert(pos != end); ++pos; advance_past_empty_and_deleted(); return *this; } iterator operator++(int /*unused*/) { auto tmp(*this); ++*this; return tmp; } // Comparison. bool operator==(const iterator& it) const { return pos == it.pos; } bool operator!=(const iterator& it) const { return pos != it.pos; } // The actual data const dense_hashtable* ht; pointer pos, end; }; // Now do it all again, but with const-ness! template struct dense_hashtable_const_iterator { private: using value_alloc_type = typename std::allocator_traits::template rebind_alloc; using value_alloc_traits = typename std::allocator_traits::template rebind_traits; public: typedef dense_hashtable_iterator iterator; typedef dense_hashtable_const_iterator const_iterator; typedef std::forward_iterator_tag iterator_category; // very little defined! typedef V value_type; typedef typename value_alloc_traits::difference_type difference_type; typedef typename value_alloc_traits::size_type size_type; typedef const typename value_alloc_traits::value_type& reference; typedef typename value_alloc_traits::const_pointer pointer; // "Real" constructor and default constructor dense_hashtable_const_iterator( const dense_hashtable* h, pointer it, pointer it_end, bool advance) : ht(h), pos(it), end(it_end) { if (advance) advance_past_empty_and_deleted(); } dense_hashtable_const_iterator() : ht(nullptr), pos(pointer()), end(pointer()) {} // This lets us convert regular iterators to const iterators dense_hashtable_const_iterator(const iterator& it) : ht(it.ht), pos(it.pos), end(it.end) {} // The default destructor is fine; we don't define one // The default operator= is fine; we don't define one // Happy dereferencer reference operator*() const { return *pos; } pointer operator->() const { return &(operator*()); } // Arithmetic. The only hard part is making sure that // we're not on an empty or marked-deleted array element void advance_past_empty_and_deleted() { while (pos != end && (ht->test_empty(*this) || ht->test_deleted(*this))) ++pos; } const_iterator& operator++() { assert(pos != end); ++pos; advance_past_empty_and_deleted(); return *this; } const_iterator operator++(int /*unused*/) { auto tmp(*this); ++*this; return tmp; } // Comparison. bool operator==(const const_iterator& it) const { return pos == it.pos; } bool operator!=(const const_iterator& it) const { return pos != it.pos; } // The actual data const dense_hashtable* ht; pointer pos, end; }; template class dense_hashtable { private: using value_alloc_type = typename std::allocator_traits::template rebind_alloc; using value_alloc_traits = typename std::allocator_traits::template rebind_traits; public: typedef Key key_type; typedef Value value_type; typedef HashFcn hasher; typedef EqualKey key_equal; typedef Alloc allocator_type; typedef typename value_alloc_traits::size_type size_type; typedef typename value_alloc_traits::difference_type difference_type; typedef typename value_alloc_traits::value_type& reference; typedef const typename value_alloc_traits::value_type& const_reference; typedef typename value_alloc_traits::pointer pointer; typedef typename value_alloc_traits::const_pointer const_pointer; typedef dense_hashtable_iterator iterator; typedef dense_hashtable_const_iterator const_iterator; // These come from tr1. For us they're the same as regular iterators. typedef iterator local_iterator; typedef const_iterator const_local_iterator; // How full we let the table get before we resize, by default. // Knuth says .8 is good -- higher causes us to probe too much, // though it saves memory. static const int HT_OCCUPANCY_PCT; // defined at the bottom of this file // How empty we let the table get before we resize lower, by default. // (0.0 means never resize lower.) // It should be less than OCCUPANCY_PCT / 2 or we thrash resizing static const int HT_EMPTY_PCT; // defined at the bottom of this file // Minimum size we're willing to let hashtables be. // Must be a power of two, and at least 4. // Note, however, that for a given hashtable, the initial size is a // function of the first constructor arg, and may be >HT_MIN_BUCKETS. static const size_type HT_MIN_BUCKETS = 4; // By default, if you don't specify a hashtable size at // construction-time, we use this size. Must be a power of two, and // at least HT_MIN_BUCKETS. static const size_type HT_DEFAULT_STARTING_BUCKETS = 32; // ITERATOR FUNCTIONS iterator begin() { return iterator(this, table, table + num_buckets, true); } iterator end() { return iterator(this, table + num_buckets, table + num_buckets, true); } const_iterator begin() const { return const_iterator(this, table, table + num_buckets, true); } const_iterator end() const { return const_iterator(this, table + num_buckets, table + num_buckets, true); } // These come from tr1 unordered_map. They iterate over 'bucket' n. // We'll just consider bucket n to be the n-th element of the table. local_iterator begin(size_type i) { return local_iterator(this, table + i, table + i + 1, false); } local_iterator end(size_type i) { local_iterator it = begin(i); if (!test_empty(i) && !test_deleted(i)) ++it; return it; } const_local_iterator begin(size_type i) const { return const_local_iterator(this, table + i, table + i + 1, false); } const_local_iterator end(size_type i) const { const_local_iterator it = begin(i); if (!test_empty(i) && !test_deleted(i)) ++it; return it; } // ACCESSOR FUNCTIONS for the things we templatize on, basically hasher hash_funct() const { return settings; } key_equal key_eq() const { return key_info; } value_alloc_type get_allocator() const { return key_info; } // Accessor function for statistics gathering. int num_table_copies() const { return settings.num_ht_copies(); } private: // Annoyingly, we can't copy values around, because they might have // const components (they're probably std::pair). We use // explicit destructor invocation and placement new to get around // this. Arg. static void set_value(pointer dst, const_reference src) { dst->~value_type(); // delete the old value, if any new (dst) value_type(src); } static void set_value(pointer dst, value_type&& src) { // NOLINT dst->~value_type(); new (dst) value_type(std::move(src)); } void destroy_buckets(size_type first, size_type last) { for (; first != last; ++first) table[first].~value_type(); } // DELETE HELPER FUNCTIONS // This lets the user describe a key that will indicate deleted // table entries. This key should be an "impossible" entry -- // if you try to insert it for real, you won't be able to retrieve it! // (NB: while you pass in an entire value, only the key part is looked // at. This is just because I don't know how to assign just a key.) private: // Gets rid of any deleted entries we have. void squash_deleted() { if (num_deleted > 0) { rebucket(settings.min_buckets(size(), num_buckets)); } assert(num_deleted == 0); } // Test if the given key is the deleted indicator. Requires // num_deleted > 0, for correctness of read(), and because that // guarantees that key_info.delkey is valid. bool test_deleted_key(const key_type& key) const { assert(num_deleted > 0); return equals(key_info.delkey, key); } public: void set_deleted_key(const key_type& key) { // the empty indicator (if specified) and the deleted indicator // must be different assert((!settings.use_empty() || !equals(key, key_info.empty)) && "Passed the empty-key to set_deleted_key"); // It's only safe to change what "deleted" means if we purge deleted guys squash_deleted(); settings.set_use_deleted(true); key_info.delkey = key; } key_type deleted_key() const { assert(settings.use_deleted() && "Must set deleted key before calling deleted_key"); return key_info.delkey; } // These are public so the iterators can use them // True if the item at position bucknum is "deleted" marker bool test_deleted(size_type bucknum) const { // Invariant: !use_deleted() implies num_deleted is 0. assert(settings.use_deleted() || num_deleted == 0); return num_deleted > 0 && test_deleted_key(get_key(table[bucknum])); } bool test_deleted(const iterator& it) const { // Invariant: !use_deleted() implies num_deleted is 0. assert(settings.use_deleted() || num_deleted == 0); return num_deleted > 0 && test_deleted_key(get_key(*it)); } bool test_deleted(const const_iterator& it) const { // Invariant: !use_deleted() implies num_deleted is 0. assert(settings.use_deleted() || num_deleted == 0); return num_deleted > 0 && test_deleted_key(get_key(*it)); } private: void check_use_deleted(const char* caller) { (void)caller; // could log it if the assert failed assert(settings.use_deleted()); } // Write the deleted key to the position specified. // Requires: !test_deleted(it) void set_deleted(iterator& it) { check_use_deleted("set_deleted()"); assert(!test_deleted(it)); // &* converts from iterator to value-type. set_key(&(*it), key_info.delkey); } // We also allow to set/clear the deleted bit on a const iterator. // We allow a const_iterator for the same reason you can delete a // const pointer: it's convenient, and semantically you can't use // 'it' after it's been deleted anyway, so its const-ness doesn't // really matter. // Requires: !test_deleted(it) void set_deleted(const_iterator& it) { check_use_deleted("set_deleted()"); assert(!test_deleted(it)); set_key(const_cast(&(*it)), key_info.delkey); } // EMPTY HELPER FUNCTIONS // This lets the user describe a key that will indicate empty (unused) // table entries. This key should be an "impossible" entry -- // if you try to insert it for real, you won't be able to retrieve it! // (NB: while you pass in an entire value, only the key part is looked // at. This is just because I don't know how to assign just a key.) public: // These are public so the iterators can use them // True if the item at position bucknum is "empty" marker bool test_empty(size_type bucknum) const { assert(settings.use_empty()); // we always need to know what's empty! return equals(key_info.empty, get_key(table[bucknum])); } bool test_empty(const iterator& it) const { assert(settings.use_empty()); // we always need to know what's empty! return equals(key_info.empty, get_key(*it)); } bool test_empty(const const_iterator& it) const { assert(settings.use_empty()); // we always need to know what's empty! return equals(key_info.empty, get_key(*it)); } private: bool test_empty(size_type bucknum, const_pointer ptable) const { assert(settings.use_empty()); return equals(key_info.empty, get_key(ptable[bucknum])); } void fill_range_with_empty(pointer table_start, pointer table_end) { for (; table_start != table_end; ++table_start) { new (table_start) value_type(); set_key(table_start, key_info.empty); } } public: // TODO(user): change all callers of this to pass in a key instead, // and take a const key_type instead of const value_type. void set_empty_key(const_reference val) { // Once you set the empty key, you can't change it assert(!settings.use_empty() && "Calling set_empty_key multiple times"); // The deleted indicator (if specified) and the empty indicator // must be different. const key_type& key = get_key(val); assert((!settings.use_deleted() || !equals(key, key_info.delkey)) && "Setting the empty key the same as the deleted key"); settings.set_use_empty(true); key_info.empty.~key_type(); new (&key_info.empty) key_type(key); assert(!table); // must set before first use // num_buckets was set in constructor even though table was nullptr table = get_internal_allocator().allocate(num_buckets); fill_range_with_empty(table, table + num_buckets); } // TODO(user): this should return the key by const reference. value_type empty_key() const { assert(settings.use_empty()); value_type ret = value_type(); set_key(&ret, key_info.empty); return ret; } // FUNCTIONS CONCERNING SIZE public: size_type size() const { return num_elements - num_deleted; } size_type max_size() const { return std::allocator_traits::max_size(get_allocator()); } bool empty() const { return size() == 0; } size_type bucket_count() const { return num_buckets; } private: // Because of the above, size_type(-1) is never legal; use it for errors static const size_type ILLEGAL_BUCKET = size_type(-1); // Used after a string of deletes. Returns true if we actually shrunk. // TODO(user): take a delta so we can take into account inserts // done after shrinking. Maybe make part of the Settings class? bool maybe_shrink() { assert(num_elements >= num_deleted); assert((bucket_count() & (bucket_count() - 1)) == 0); // is a power of two assert(bucket_count() >= HT_MIN_BUCKETS); bool retval = false; // If you construct a hashtable with < HT_DEFAULT_STARTING_BUCKETS, // we'll never shrink until you get relatively big, and we'll never // shrink below HT_DEFAULT_STARTING_BUCKETS. Otherwise, something // like "dense_hash_set x; x.insert(4); x.erase(4);" will // shrink us down to HT_MIN_BUCKETS buckets, which is too small. const size_type num_remain = num_elements - num_deleted; const size_type shrink_threshold = settings.shrink_threshold(); if (shrink_threshold > 0 && num_remain < shrink_threshold && bucket_count() > HT_DEFAULT_STARTING_BUCKETS) { const float shrink_factor = settings.shrink_factor(); size_type sz = bucket_count() / 2; // find how much we should shrink while (sz > HT_DEFAULT_STARTING_BUCKETS && num_remain < sz * shrink_factor) { sz /= 2; // stay a power of 2 } rebucket(sz); retval = true; } settings.set_consider_shrink(false); // because we just considered it return retval; } // We'll let you resize a hashtable -- though this makes us copy all! // When you resize, you say, "make it big enough for this many more elements" // Returns true if we actually resized, false if size was already ok. bool resize_delta(size_type delta) { bool did_resize = false; if (settings.consider_shrink()) { // see if lots of deletes happened if (maybe_shrink()) did_resize = true; } if (num_elements >= std::numeric_limits::max() - delta) { throw std::length_error("resize overflow"); } assert(settings.enlarge_threshold() < bucket_count()); // Check if our work is done. if (bucket_count() >= HT_MIN_BUCKETS && num_elements + delta <= settings.enlarge_threshold()) { return did_resize; } // Sometimes, we need to resize just to get rid of all the // "deleted" buckets that are clogging up the hashtable. So when // deciding whether to resize, count the deleted buckets (which // are currently taking up room). But later, when we decide what // size to resize to, *don't* count deleted buckets, since they // get discarded during the resize. const size_type needed_size = settings.min_buckets(num_elements + delta, 0); if (needed_size <= bucket_count()) // we have enough buckets return did_resize; // We will rebucket. size_type resize_to = settings.min_buckets( num_elements - num_deleted + delta, bucket_count()); if (resize_to < needed_size) { // This situation means that we have enough deleted elements, // that once we purge them, we won't actually have needed to // grow. But we may want to grow anyway: if we just purge one // element, say, we'll have to grow anyway next time we // insert. Might as well grow now, since we're already going // through the trouble of rebucketing in order to purge the // deleted elements. (Safety note: Can resize_to * 2 overflow? No. // The output of min_buckets() is always a power of two, so resize_to // and needed_size are powers of two. That plus resize_to < needed_size // proves that overflow isn't a concern.) const size_type target = static_cast(settings.shrink_size(resize_to * 2)); if (num_elements - num_deleted + delta >= target) { // Good, we won't be below the shrink threshold even if we double. resize_to *= 2; } } rebucket(resize_to); return true; } // We require table be non-null and empty before calling this. void resize_table(size_type old_size, size_type new_size) { get_internal_allocator().deallocate(table, old_size); table = get_internal_allocator().allocate(new_size); } // Copy (or, if Iter is a move_iterator, move) the elements from // [src_first, src_last) into dest_table, which we assume has size // dest_bucket_count and has been initialized to the empty key. template void copy_elements(Iter src_first, Iter src_last, pointer dest_table, size_type dest_bucket_count) { assert((dest_bucket_count & (dest_bucket_count - 1)) == 0); // a power of 2 // We use a normal iterator to get non-deleted bcks from ht // We could use insert() here, but since we know there are // no duplicates and no deleted items, we can be more efficient for (; src_first != src_last; ++src_first) { size_type num_probes = 0; // how many times we've probed size_type bucknum; const size_type bucket_count_minus_one = dest_bucket_count - 1; for (bucknum = hash(get_key(*src_first)) & bucket_count_minus_one; !test_empty(bucknum, dest_table); // not empty bucknum = (bucknum + JUMP_(key, num_probes)) & bucket_count_minus_one) { ++num_probes; assert(num_probes < dest_bucket_count && "Hashtable is full: an error in key_equal<> or hash<>"); } // Copies or moves the value into dest_table. set_value(&dest_table[bucknum], *src_first); } } // Used to actually do the rehashing when we grow/shrink a hashtable void copy_from(const dense_hashtable& ht, size_type min_buckets_wanted) { size_type size = ht.size(); // clear_to_size() sets ht.size() to 0. clear_to_size(settings.min_buckets(ht.size(), min_buckets_wanted)); copy_elements(ht.begin(), ht.end(), table, bucket_count()); num_elements = size; settings.inc_num_ht_copies(); } // Rebuckets and resizes the hashtable. Gets rid of any deleted entries. void rebucket(size_type new_num_buckets) { if (table == nullptr) { // When we eventually allocate the table, it will have this many buckets. num_buckets = new_num_buckets; return; } assert(settings.use_empty()); assert((new_num_buckets & (new_num_buckets - 1)) == 0); // a power of two // If settings.shrink_factor() is zero then we must not shrink. assert(settings.shrink_factor() > 0 || new_num_buckets >= num_buckets); pointer new_table = get_internal_allocator().allocate(new_num_buckets); fill_range_with_empty(new_table, new_table + new_num_buckets); copy_elements(std::make_move_iterator(begin()), std::make_move_iterator(end()), new_table, new_num_buckets); destroy_buckets(0, num_buckets); // Destroy table's elements. get_internal_allocator().deallocate(table, num_buckets); table = new_table; num_buckets = new_num_buckets; assert(num_elements >= num_deleted); num_elements -= num_deleted; num_deleted = 0; settings.reset_thresholds(bucket_count()); settings.inc_num_ht_copies(); } // Required by the spec for hashed associative container public: // Though the docs say this should be num_buckets, I think it's much // more useful as num_elements. As a special feature, calling with // req_elements==0 will cause us to shrink if we can, saving space. void resize(size_type req_elements) { // resize to this or larger if (settings.consider_shrink() || req_elements == 0) maybe_shrink(); if (req_elements > num_elements) resize_delta(req_elements - num_elements); } // Get and change the value of shrink_factor and enlarge_factor. The // description at the beginning of this file explains how to choose // the values. Setting the shrink parameter to 0.0 ensures that the // table never shrinks. void get_resizing_parameters(float* shrink, float* grow) const { *shrink = settings.shrink_factor(); *grow = settings.enlarge_factor(); } void set_resizing_parameters(float shrink, float grow) { settings.set_resizing_parameters(shrink, grow); settings.reset_thresholds(bucket_count()); } // CONSTRUCTORS -- as required by the specs, we take a size, // but also let you specify a hashfunction, key comparator, // and key extractor. We also define a copy constructor and =. // DESTRUCTOR -- needs to free the table explicit dense_hashtable(size_type expected_max_items_in_table = 0, const HashFcn& hf = HashFcn(), const EqualKey& eql = EqualKey(), const ExtractKey& ext = ExtractKey(), const SetKey& set = SetKey(), const Alloc& alloc = Alloc()) : settings(hf), key_info(ext, set, eql, value_alloc_type(alloc)), num_deleted(0), num_elements(0), num_buckets(expected_max_items_in_table == 0 ? HT_DEFAULT_STARTING_BUCKETS : settings.min_buckets(expected_max_items_in_table, 0)), table(nullptr) { // table is nullptr until the empty key is set. However, we set num_buckets // here so we know how much space to allocate once the empty key is set. settings.reset_thresholds(bucket_count()); } // As a convenience for resize(), we allow an optional second argument // which lets you make this new hashtable a different size than ht dense_hashtable(const dense_hashtable& ht, size_type min_buckets_wanted = HT_DEFAULT_STARTING_BUCKETS) : settings(ht.settings), key_info(ht.key_info.as_extract_key(), ht.key_info.as_set_key(), ht.key_info.as_equal_key(), value_alloc_type(std::allocator_traits:: select_on_container_copy_construction( ht.key_info.as_value_alloc()))), num_deleted(0), num_elements(0), num_buckets(0), table(nullptr) { key_info.delkey = ht.key_info.delkey; key_info.empty = ht.key_info.empty; if (!ht.settings.use_empty()) { // If use_empty isn't set, copy_from will crash, so we do our own copying. assert(ht.empty()); num_buckets = settings.min_buckets(ht.size(), min_buckets_wanted); settings.reset_thresholds(bucket_count()); return; } settings.reset_thresholds(bucket_count()); copy_from(ht, min_buckets_wanted); // copy_from() ignores deleted entries } dense_hashtable& operator=(const dense_hashtable& ht) { if (&ht == this) return *this; // don't copy onto ourselves settings = ht.settings; key_info.as_extract_key() = ht.key_info.as_extract_key(); key_info.as_set_key() = ht.key_info.as_set_key(); key_info.as_equal_key() = ht.key_info.as_equal_key(); if (std::allocator_traits< value_alloc_type>::propagate_on_container_copy_assignment::value) { // If we're about to overwrite our allocator, we need to free all // memory using our old allocator. if (key_info.as_value_alloc() != ht.key_info.as_value_alloc()) { destroy_table(); } static_cast(key_info) = static_cast(ht.key_info); } key_info.empty = ht.key_info.empty; key_info.delkey = ht.key_info.delkey; if (ht.settings.use_empty()) { // copy_from() calls clear and sets num_deleted to 0 too copy_from(ht, HT_MIN_BUCKETS); } else { assert(ht.empty()); destroy_table(); } // we purposefully don't copy the allocator, which may not be copyable return *this; } dense_hashtable(dense_hashtable&& ht) noexcept : settings(std::move(ht.settings)), key_info(std::move(ht.key_info)), num_deleted(ht.num_deleted), num_elements(ht.num_elements), num_buckets(ht.num_buckets), table(ht.table) { ht.num_deleted = 0; ht.num_elements = 0; ht.table = nullptr; ht.num_buckets = HT_DEFAULT_STARTING_BUCKETS; ht.settings.set_use_empty(false); ht.settings.set_use_deleted(false); } dense_hashtable& operator=(dense_hashtable&& ht) noexcept { if (&ht == this) return *this; // don't move onto ourselves const bool can_move_table = std::allocator_traits< Alloc>::propagate_on_container_move_assignment::value || key_info.as_value_alloc() == ht.key_info.as_value_alloc(); // First, deallocate with this's allocator. destroy_table(); if (std::allocator_traits< value_alloc_type>::propagate_on_container_move_assignment::value) { // This moves the allocator. key_info = std::move(ht.key_info); } else { // Move all other base classes of key_info from ht, but don't move the // allocator. key_info.as_extract_key() = std::move(ht.key_info.as_extract_key()); key_info.as_set_key() = std::move(ht.key_info.as_set_key()); key_info.as_equal_key() = std::move(ht.key_info.as_equal_key()); key_info.delkey = std::move(ht.key_info.delkey); key_info.empty = std::move(ht.key_info.empty); } settings = std::move(ht.settings); num_deleted = ht.num_deleted; ht.num_deleted = 0; num_elements = ht.num_elements; ht.num_elements = 0; num_buckets = ht.num_buckets; ht.num_buckets = HT_DEFAULT_STARTING_BUCKETS; ht.settings.set_use_empty(false); ht.settings.set_use_deleted(false); if (can_move_table) { // We can transfer ownership of the table from ht to this because either // we're propagating the allocator or ht's allocator is equal to this's. table = ht.table; ht.table = nullptr; } else if (ht.table) { // We can't transfer ownership of any memory from ht to this, so the // best we can do is move element-by-element. table = get_internal_allocator().allocate(num_buckets); for (size_type i = 0; i < num_buckets; ++i) { new (table + i) Value(std::move(ht.table[i])); } ht.destroy_table(); } return *this; } ~dense_hashtable() { destroy_table(); } // Many STL algorithms use swap instead of copy constructors void swap(dense_hashtable& ht) noexcept { if (this == &ht) return; // swap with self. using std::swap; swap(settings, ht.settings); // Swap everything in key_info but the allocator. swap(key_info.as_extract_key(), ht.key_info.as_extract_key()); swap(key_info.as_set_key(), ht.key_info.as_set_key()); swap(key_info.as_equal_key(), ht.key_info.as_equal_key()); if (std::allocator_traits< value_alloc_type>::propagate_on_container_swap::value) { swap(static_cast(key_info), static_cast(ht.key_info)); } else { // Swapping when allocators are unequal and // propagate_on_container_swap is false is undefined behavior. ABSL_CHECK(key_info.as_value_alloc() == ht.key_info.as_value_alloc()); } swap(key_info.empty, ht.key_info.empty); swap(key_info.delkey, ht.key_info.delkey); swap(num_deleted, ht.num_deleted); swap(num_elements, ht.num_elements); swap(num_buckets, ht.num_buckets); swap(table, ht.table); } private: void destroy_table() { if (table) { destroy_buckets(0, num_buckets); get_internal_allocator().deallocate(table, num_buckets); table = nullptr; } } void clear_to_size(size_type new_num_buckets) { if (!table) { table = get_internal_allocator().allocate(new_num_buckets); } else { destroy_buckets(0, num_buckets); if (new_num_buckets != num_buckets) { // resize, if necessary resize_table(num_buckets, new_num_buckets); } } assert(table); fill_range_with_empty(table, table + new_num_buckets); num_elements = 0; num_deleted = 0; num_buckets = new_num_buckets; // our new size settings.reset_thresholds(bucket_count()); } public: // It's always nice to be able to clear a table without deallocating it void clear() { // If the table is already empty, and the number of buckets is // already as we desire, there's nothing to do. const size_type new_num_buckets = settings.min_buckets(0, 0); if (num_elements == 0 && new_num_buckets == num_buckets) { return; } clear_to_size(new_num_buckets); } // Clear the table without resizing it. // Mimics the stl_hashtable's behaviour when clear()-ing in that it // does not modify the bucket count void clear_no_resize() { if (num_elements > 0) { assert(table); destroy_buckets(0, num_buckets); fill_range_with_empty(table, table + num_buckets); } // don't consider to shrink before another erase() settings.reset_thresholds(bucket_count()); num_elements = 0; num_deleted = 0; } // LOOKUP ROUTINES private: template void assert_key_is_not_empty_or_deleted(const K& key) const { assert(settings.use_empty() && "set_empty_key() was not called"); assert(!equals(key, key_info.empty) && "Using the empty key as a regular key"); assert((!settings.use_deleted() || !equals(key, key_info.delkey)) && "Using the deleted key as a regular key"); } // Returns a pair of positions: 1st where the object is, 2nd where // it would go if you wanted to insert it. 1st is ILLEGAL_BUCKET // if object is not found; 2nd is ILLEGAL_BUCKET if it is. // Note: because of deletions where-to-insert is not trivial: it's the // first deleted bucket we see, as long as we don't find the key later template std::pair find_position_using_hash( const size_type key_hash, const K& key) const { assert_key_is_not_empty_or_deleted(key); size_type num_probes = 0; // how many times we've probed const size_type bucket_count_minus_one = bucket_count() - 1; size_type bucknum = key_hash & bucket_count_minus_one; size_type insert_pos = ILLEGAL_BUCKET; // where we would insert while (true) { // probe until something happens if (test_empty(bucknum)) { // bucket is empty if (insert_pos == ILLEGAL_BUCKET) // found no prior place to insert return std::pair(ILLEGAL_BUCKET, bucknum); else return std::pair(ILLEGAL_BUCKET, insert_pos); } else if (test_deleted(bucknum)) { // keep searching, but mark to insert if (insert_pos == ILLEGAL_BUCKET) insert_pos = bucknum; } else if (equals(key, get_key(table[bucknum]))) { return std::pair(bucknum, ILLEGAL_BUCKET); } ++num_probes; // we're doing another probe bucknum = (bucknum + JUMP_(key, num_probes)) & bucket_count_minus_one; assert(num_probes < bucket_count() && "Hashtable is full: an error in key_equal<> or hash<>"); } } template std::pair find_if_present(const K& key) const { return find_if_present_using_hash(hash(key), key); } // Return where the key is (if at all), and if it is present. If // the key isn't present then the first part of the return value is // undefined. The same information can be extracted from the result // of find_position(), but that tends to be slower in practice. template std::pair find_if_present_using_hash( const size_type key_hash, const K& key) const { assert_key_is_not_empty_or_deleted(key); size_type num_probes = 0; // how many times we've probed const size_type bucket_count_minus_one = bucket_count() - 1; size_type bucknum = key_hash & bucket_count_minus_one; while (true) { // probe until something happens if (equals(key, get_key(table[bucknum]))) { return std::pair(bucknum, true); } else if (test_empty(bucknum)) { return std::pair(0, false); } ++num_probes; // we're doing another probe bucknum = (bucknum + JUMP_(key, num_probes)) & bucket_count_minus_one; assert(num_probes < bucket_count() && "Hashtable is full: an error in key_equal<> or hash<>"); } } private: template iterator find_impl(const K& key) { std::pair pos = find_if_present(key); return pos.second ? iterator(this, table + pos.first, table + num_buckets, false) : end(); } template const_iterator find_impl(const K& key) const { std::pair pos = find_if_present(key); return pos.second ? const_iterator(this, table + pos.first, table + num_buckets, false) : end(); } template size_type count_impl(const K& key) const { return find_if_present(key).second ? 1 : 0; } template std::pair equal_range_impl(const K& key) { iterator pos = find(key); if (pos == end()) { return std::pair(pos, pos); } else { const iterator startpos = pos++; return std::pair(startpos, pos); } } template std::pair equal_range_impl( const K& key) const { const_iterator pos = find(key); if (pos == end()) { return std::pair(pos, pos); } else { const const_iterator startpos = pos++; return std::pair(startpos, pos); } } public: iterator find(const key_type& key) { return find_impl(key); } const_iterator find(const key_type& key) const { return find_impl(key); } // Counts how many elements have key key. For maps, it's either 0 or 1. size_type count(const key_type& key) const { return count_impl(key); } // Likewise, equal_range doesn't really make sense for us. Oh well. std::pair equal_range(const key_type& key) { return equal_range_impl(key); } std::pair equal_range( const key_type& key) const { return equal_range_impl(key); } // INSERTION ROUTINES private: // Private method used by insert_noresize and find_or_insert. // 'obj' is either value_type&& or const value_type&. template iterator insert_at(U&& obj, size_type pos) { if (size() >= max_size()) { throw std::length_error("insert overflow"); } if (test_deleted(pos)) { // just replace if it's been del. assert(num_deleted > 0); --num_deleted; // used to be, now it isn't } else { ++num_elements; // replacing an empty bucket } set_value(&table[pos], std::forward(obj)); return iterator(this, table + pos, table + num_buckets, false); } // If you know *this is big enough to hold obj, use this routine // 'obj' is value_type&& or const value_type&. template std::pair insert_noresize(U&& obj) { // NOLINT return insert_noresize_using_hash(hash(get_key(obj)), std::forward(obj)); } // If you know *this is big enough to hold obj, use this routine // 'obj' is value_type&& or const value_type&. template std::pair insert_noresize_using_hash(const size_type key_hash, U&& obj) { const std::pair pos = find_position_using_hash(key_hash, get_key(obj)); if (pos.first != ILLEGAL_BUCKET) { // object was already there return std::pair( iterator(this, table + pos.first, table + num_buckets, false), false); // false: we didn't insert } else { // pos.second says where to put it iterator i = insert_at(std::forward(obj), pos.second); return std::pair(i, true); } } // Specializations of insert(it, it) depending on the power of the iterator: // (1) Iterator supports operator-, resize before inserting template void insert(ForwardIterator f, ForwardIterator l, std::forward_iterator_tag) { size_t dist = std::distance(f, l); if (dist >= std::numeric_limits::max()) { throw std::length_error("insert-range overflow"); } resize_delta(static_cast(dist)); for (; dist > 0; --dist, ++f) { insert_noresize(*f); } } // (2) Arbitrary iterator, can't tell how much to resize template void insert(InputIterator f, InputIterator l, std::input_iterator_tag) { for (; f != l; ++f) insert(*f); } public: // This is the normal insert routine, used by the outside world std::pair insert(const value_type& obj) { resize_delta(1); // adding an object, grow if need be return insert_noresize(obj); } std::pair insert(value_type&& obj) { // NOLINT resize_delta(1); // adding an object, grow if need be return insert_noresize(std::move(obj)); } // When inserting a lot at a time, we specialize on the type of iterator template void insert(InputIterator f, InputIterator l) { // specializes on iterator type insert(f, l, typename std::iterator_traits::iterator_category()); } template value_type& find_or_insert(const key_type& key) { return find_or_insert_using_hash(hash(key), key); } // DefaultValue is a functor that takes a key and returns a value_type // representing the default value to be inserted if none is found. template value_type& find_or_insert_using_hash(const size_type key_hash, const key_type& key) { const std::pair pos = find_position_using_hash(key_hash, key); DefaultValue default_value; if (pos.first != ILLEGAL_BUCKET) { // object was already there return table[pos.first]; } else if (resize_delta(1)) { // needed to rehash to make room // Since we resized, we can't use pos, so recalculate where to insert. return *insert_noresize(default_value(key)).first; } else { // no need to rehash, insert right here return *insert_at(default_value(key), pos.second); } } // DELETION ROUTINES private: template size_type erase_impl(const K& key) { iterator pos = find(key); if (pos != end()) { assert(!test_deleted(pos)); // or find() shouldn't have returned it set_deleted(pos); ++num_deleted; // will think about shrink after next insert settings.set_consider_shrink(true); return 1; // because we deleted one thing } else { return 0; // because we deleted nothing } } public: size_type erase(const key_type& key) { return erase_impl(key); } void erase(iterator pos) { if (pos == end()) return; set_deleted(pos); ++num_deleted; // will think about shrink after next insert settings.set_consider_shrink(true); } void erase(iterator f, iterator l) { for (; f != l; ++f) { set_deleted(f); ++num_deleted; } // will think about shrink after next insert settings.set_consider_shrink(true); } // We allow you to erase a const_iterator just like we allow you to // erase an iterator. This is in parallel to 'delete': you can delete // a const pointer just like a non-const pointer. The logic is that // you can't use the object after it's erased anyway, so it doesn't matter // if it's const or not. void erase(const_iterator pos) { if (pos == end()) return; set_deleted(pos); ++num_deleted; // will think about shrink after next insert settings.set_consider_shrink(true); } void erase(const_iterator f, const_iterator l) { for (; f != l; ++f) { set_deleted(f); ++num_deleted; } // will think about shrink after next insert settings.set_consider_shrink(true); } // COMPARISON bool operator==(const dense_hashtable& ht) const { if (size() != ht.size()) { return false; } else if (this == &ht) { return true; } else { // Iterate through the elements in "this" and see if the // corresponding element is in ht for (const_iterator it = begin(); it != end(); ++it) { const_iterator it2 = ht.find(get_key(*it)); if ((it2 == ht.end()) || (*it != *it2)) { return false; } } return true; } } bool operator!=(const dense_hashtable& ht) const { return !(*this == ht); } // I/O // We support reading and writing hashtables to disk. Alas, since // I don't know how to write a hasher or key_equal, you have to make // sure everything but the table is the same. We compact before writing. private: // Every time the disk format changes, this should probably change too typedef unsigned long MagicNumberType; static const MagicNumberType MAGIC_NUMBER = 0x13578642; // Package functors with another class to eliminate memory needed for // zero-size functors. Since ExtractKey and hasher's operator() might // have the same function signature, they must be packaged in // different classes. struct Settings : sh_hashtable_settings { explicit Settings(const hasher& hf) : sh_hashtable_settings( hf, HT_OCCUPANCY_PCT / 100.0f, HT_EMPTY_PCT / 100.0f) {} }; // Packages ExtractKey, SetKey, EqualKey functors, allocator and deleted and // empty key values. struct KeyInfo : public ExtractKey, public SetKey, public EqualKey, public value_alloc_type { KeyInfo(const ExtractKey& ek, const SetKey& sk, const EqualKey& eq, const value_alloc_type& a) : ExtractKey(ek), SetKey(sk), EqualKey(eq), value_alloc_type(a), delkey(), empty() {} // Accessors for convenient access to base classes. ExtractKey& as_extract_key() { return *this; } const ExtractKey& as_extract_key() const { return *this; } SetKey& as_set_key() { return *this; } const SetKey& as_set_key() const { return *this; } EqualKey& as_equal_key() { return *this; } const EqualKey& as_equal_key() const { return *this; } value_alloc_type& as_value_alloc() { return *this; } const value_alloc_type& as_value_alloc() const { return *this; } // We want to return the exact same type as ExtractKey: Key or const Key& typename ExtractKey::result_type get_key(const_reference v) const { return ExtractKey::operator()(v); } void set_key(pointer v, const key_type& k) const { SetKey::operator()(v, k); } // We only ever call EqualKey::operator()(key_type, K) -- we never use the // other order of args. This allows consumers to get away with implementing // only half of operator==. template bool equals(const key_type& a, const K& b) const { return EqualKey::operator()(a, b); } // Which key marks deleted entries. // TODO(user): make a pointer, and get rid of use_deleted (benchmark!) typename std::remove_const::type delkey; // Key value used to mark unused entries. typename std::remove_const::type empty; }; // Returns the value_alloc_type used to allocate and deallocate // the table. This can be different from the one returned by get_allocator(). value_alloc_type& get_internal_allocator() { return key_info; } // Utility functions to access the templated operators size_type hash(const key_type& v) const { return settings.hash(v); } bool equals(const key_type& a, const key_type& b) const { return key_info.equals(a, b); } typename ExtractKey::result_type get_key(const_reference v) const { return key_info.get_key(v); } void set_key(pointer v, const key_type& k) const { key_info.set_key(v, k); } private: // Actual data Settings settings; KeyInfo key_info; size_type num_deleted; // how many occupied buckets are marked deleted size_type num_elements; size_type num_buckets; pointer table; }; // We need a global swap as well template inline void swap(dense_hashtable& x, dense_hashtable& y) noexcept { x.swap(y); } #undef JUMP_ #undef PUT_ #undef GET_ template const typename dense_hashtable::size_type dense_hashtable::ILLEGAL_BUCKET; // How full we let the table get before we resize. Knuth says .8 is // good -- higher causes us to probe too much, though saves memory. // However, we go with .5, getting better performance at the cost of // more space (a trade-off densehashtable explicitly chooses to make). // Feel free to play around with different values, though, via // max_load_factor() and/or set_resizing_parameters(). template const int dense_hashtable::HT_OCCUPANCY_PCT = 50; // How empty we let the table get before we resize lower. // It should be less than OCCUPANCY_PCT / 2 or we thrash resizing. template const int dense_hashtable::HT_EMPTY_PCT = static_cast( 0.4 * dense_hashtable::HT_OCCUPANCY_PCT); } #endif // S2_UTIL_GTL_DENSEHASHTABLE_H_ src/s2/util/gtl/hashtable_common.h000066400000000000000000000211271524103652300174140ustar00rootroot00000000000000// Copyright 2010 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // --- #ifndef S2_UTIL_GTL_HASHTABLE_COMMON_H_ #define S2_UTIL_GTL_HASHTABLE_COMMON_H_ #include #include #include #include // For length_error // Settings contains parameters for growing and shrinking the table. // It also packages zero-size functor (ie. hasher). One invariant // enforced in enlarge_size() is that we never allow all slots // occupied. (This is unlikely to matter to users, because using // a load near 1 is slow and not recommended. It allows other code // to assume there is at least one empty bucket.) // // It does some munging of the hash value in cases where we think // (fear) the original hash function might not be very good. In // particular, the default hash of pointers is the identity hash, // so probably all the low bits are 0. We identify when we think // we're hashing a pointer, and chop off the low bits. Note this // isn't perfect: even when the key is a pointer, we can't tell // for sure that the hash is the identity hash. If it's not, this // is needless work (and possibly, though not likely, harmful). template class sh_hashtable_settings : public HashFunc { public: typedef Key key_type; typedef HashFunc hasher; typedef SizeType size_type; public: sh_hashtable_settings(const hasher& hf, const float ht_occupancy_flt, const float ht_empty_flt) : hasher(hf), enlarge_threshold_(0), shrink_threshold_(0), consider_shrink_(false), use_empty_(false), use_deleted_(false), num_ht_copies_(0) { set_enlarge_factor(ht_occupancy_flt); set_shrink_factor(ht_empty_flt); } template size_type hash(const K& v) const { // We munge the hash value when we don't trust hasher::operator(). It is // very important that we use hash_munger instead of hash_munger. // Within a given hashtable, all hash values must be munged in the same way. return hash_munger::MungedHash(hasher::operator()(v)); } float enlarge_factor() const { return enlarge_factor_; } void set_enlarge_factor(float f) { enlarge_factor_ = f; } float shrink_factor() const { return shrink_factor_; } void set_shrink_factor(float f) { shrink_factor_ = f; } size_type enlarge_threshold() const { return enlarge_threshold_; } void set_enlarge_threshold(size_type t) { enlarge_threshold_ = t; } size_type shrink_threshold() const { return shrink_threshold_; } void set_shrink_threshold(size_type t) { shrink_threshold_ = t; } size_type enlarge_size(size_type x) const { return std::min(x - 1, x * enlarge_factor_); } size_type shrink_size(size_type x) const { return static_cast(x * shrink_factor_); } bool consider_shrink() const { return consider_shrink_; } void set_consider_shrink(bool t) { consider_shrink_ = t; } bool use_empty() const { return use_empty_; } void set_use_empty(bool t) { use_empty_ = t; } bool use_deleted() const { return use_deleted_; } void set_use_deleted(bool t) { use_deleted_ = t; } size_type num_ht_copies() const { return static_cast(num_ht_copies_); } void inc_num_ht_copies() { ++num_ht_copies_; } // Reset the enlarge and shrink thresholds void reset_thresholds(size_type num_buckets) { set_enlarge_threshold(enlarge_size(num_buckets)); set_shrink_threshold(shrink_size(num_buckets)); // whatever caused us to reset already considered set_consider_shrink(false); } // Caller is responsible for calling reset_threshold right after // set_resizing_parameters. void set_resizing_parameters(float shrink, float grow) { assert(shrink >= 0.0); assert(grow <= 1.0); if (shrink > grow / 2.0f) shrink = grow / 2.0f; // otherwise we thrash hashtable size set_shrink_factor(shrink); set_enlarge_factor(grow); } // This is the smallest size a hashtable can be without being too crowded. // If you like, you can give a min #buckets as well as a min #elts. // This is guaranteed to return a power of two. size_type min_buckets(size_type num_elts, size_type min_buckets_wanted) { float enlarge = enlarge_factor(); size_type sz = HT_MIN_BUCKETS; // min buckets allowed while (sz < min_buckets_wanted || num_elts >= static_cast(sz * enlarge)) { // This just prevents overflowing size_type, since sz can exceed // max_size() here. if (static_cast(sz * 2) < sz) { throw std::length_error("resize overflow"); // protect against overflow } sz *= 2; } return sz; } private: template class hash_munger { public: static size_t MungedHash(size_t hash) { return hash; } }; // This matches when the hashtable key is a pointer. template class hash_munger { public: static size_t MungedHash(size_t hash) { // TODO(user): consider rotating instead: // static const int shift = (sizeof(void *) == 4) ? 2 : 3; // return (hash << (sizeof(hash) * 8) - shift)) | (hash >> shift); // This matters if we ever change sparse/dense_hash_* to compare // hashes before comparing actual values. It's speedy on x86. return hash / sizeof(void*); // get rid of known-0 bits } }; size_type enlarge_threshold_; // table.size() * enlarge_factor size_type shrink_threshold_; // table.size() * shrink_factor float enlarge_factor_; // how full before resize float shrink_factor_; // how empty before resize // consider_shrink=true if we should try to shrink before next insert bool consider_shrink_; bool use_empty_; // used only by densehashtable, not sparsehashtable bool use_deleted_; // false until delkey has been set // num_ht_copies is a counter incremented every Copy/Move unsigned int num_ht_copies_; }; // This traits class checks whether T::is_transparent exists and names a type. // // struct Foo { using is_transparent = void; }; // struct Bar {}; // static_assert(sh_is_transparent::value, "Foo is transparent."); // staitc_assert(!sh_is_transparent::value, "Bar is not transparent."); template struct sh_is_transparent { private: struct No {}; struct Yes { No x[2]; }; template static Yes Test(typename U::is_transparent*); template static No Test(...); public: enum { value = sizeof(Test(nullptr)) == sizeof(Yes) }; }; #endif // S2_UTIL_GTL_HASHTABLE_COMMON_H_ src/s2/util/gtl/requires.h000066400000000000000000000017561524103652300157560ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_UTIL_GTL_REQUIRES_H_ #define S2_UTIL_GTL_REQUIRES_H_ #include namespace gtl { // C++17 port of C++20's `requires` expressions. // https://en.cppreference.com/w/cpp/language/constraints#Requires_expressions template constexpr bool Requires(F) { return std::is_invocable_v; } } // namespace gtl #endif // S2_UTIL_GTL_REQUIRES_H_ src/s2/util/gtl/unaligned.h000066400000000000000000000020531524103652300160540ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_UTIL_GTL_UNALIGNED_H_ #define S2_UTIL_GTL_UNALIGNED_H_ #include namespace gtl { template T UnalignedLoad(const char *p) { static_assert(std::is_trivially_copyable_v); T v; memcpy(&v, p, sizeof(v)); return v; } template void UnalignedStore(T v, char *p) { static_assert(std::is_trivially_copyable_v); memcpy(p, &v, sizeof(v)); } } // namespace gtl #endif // S2_UTIL_GTL_UNALIGNED_H_ src/s2/util/gtl/value_or_die.h000066400000000000000000000017441524103652300165510ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #ifndef S2_UTIL_GTL_VALUE_OR_DIE_H_ #define S2_UTIL_GTL_VALUE_OR_DIE_H_ #include namespace gtl { // Equivalent to `std::move(v).value()`, but makes explicit that the behavior // is to die if `v` does not contain a value. template T ValueOrDie(absl::StatusOr&& v) { return std::move(v).value(); } } // namespace gtl #endif // S2_UTIL_GTL_VALUE_OR_DIE_H_ src/s2/util/hash/000077500000000000000000000000001524103652300140725ustar00rootroot00000000000000src/s2/util/hash/BUILD.bazel000066400000000000000000000002321524103652300157450ustar00rootroot00000000000000load("@rules_cc//cc:defs.bzl", "cc_library") package(default_visibility = ["//:__subpackages__"]) cc_library( name = "mix", hdrs = ["mix.h"], ) src/s2/util/hash/mix.h000066400000000000000000000046571524103652300150540ustar00rootroot00000000000000// Copyright 2013 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: jyrki@google.com (Jyrki Alakuijala) // // This file contains routines for mixing hashes. #ifndef S2_UTIL_HASH_MIX_H_ #define S2_UTIL_HASH_MIX_H_ #include #include // Fast mixing of hash values -- not strong enough for fingerprinting. // May change from time to time. // // Values given are expected to be hashes from good hash functions. // What constitutes a good hash may depend on your application. As a rule of // thumb, if std::hash is strong enough for your hashing need if // your data were just ints, it will most likely be the correct choice // for a mixed hash of data members. HashMix does one round of multiply and // rotate mixing, so you get some additional collision avoidance guarantees // compared to just using std::hash directly. // // Possible use: // // struct Xyzzy { // int x; // int y; // string id; // }; // // #ifndef SWIG // template<> struct XyzzyHash { // size_t operator()(const Xyzzy& c) const { // HashMix mix(hash()(c.x)); // mix.Mix(hash()(c.y)); // mix.Mix(GoodFastHash()(c.id)); // return mix.get(); // } // } // #endif // // HashMix is a lower level interface than std::hash>. // Use std::hash> instead of HashMix where appropriate. class HashMix { public: HashMix() : hash_(1) {} explicit HashMix(size_t val) : hash_(val + 83) {} void Mix(size_t val) { static const size_t kMul = static_cast(0xdc3eb94af8ab4c93ULL); // Multiplicative hashing will mix bits better in the msb end ... hash_ *= kMul; // ... and rotating will move the better mixed msb-bits to lsb-bits. hash_ = ((hash_ << 19) | (hash_ >> (std::numeric_limits::digits - 19))) + val; } size_t get() const { return hash_; } private: size_t hash_; }; #endif // S2_UTIL_HASH_MIX_H_ src/s2/util/math/000077500000000000000000000000001524103652300141005ustar00rootroot00000000000000src/s2/util/math/BUILD.bazel000066400000000000000000000010151524103652300157530ustar00rootroot00000000000000load("@rules_cc//cc:defs.bzl", "cc_library") package(default_visibility = ["//:__subpackages__"]) cc_library( name = "mathutil", srcs = ["mathutil.cc"], hdrs = ["mathutil.h"], ) cc_library( name = "matrix3x3", hdrs = ["matrix3x3.h"], deps = [ ":mathutil", ":vector", "@abseil-cpp//absl/log:absl_check", ], ) cc_library( name = "vector", hdrs = ["vector.h"], deps = [ "@abseil-cpp//absl/log:absl_check", "@abseil-cpp//absl/utility", ], ) src/s2/util/math/exactfloat/000077500000000000000000000000001524103652300162325ustar00rootroot00000000000000src/s2/util/math/exactfloat/BUILD.bazel000066400000000000000000000037151524103652300201160ustar00rootroot00000000000000load("@rules_cc//cc:defs.bzl", "cc_library", "cc_test") package(default_visibility = ["//:__subpackages__"]) cc_library( name = "bignum", srcs = ["bignum.cc"], hdrs = ["bignum.h"], visibility = ["//visibility:private"], deps = [ "@abseil-cpp//absl/algorithm:container", "@abseil-cpp//absl/container:inlined_vector", "@abseil-cpp//absl/log:absl_check", ], ) cc_library( name = "exactfloat", srcs = [ "exactfloat.cc", ], hdrs = [ "exactfloat.h", ], deps = [ ":bignum", "@abseil-cpp//absl/container:inlined_vector", "@abseil-cpp//absl/log:absl_check", "@abseil-cpp//absl/log:absl_log", "@abseil-cpp//absl/numeric:bits", "@abseil-cpp//absl/numeric:int128", "@abseil-cpp//absl/random:random", ], ) cc_test( name = "bignum_test", srcs = ["bignum_test.cc"], deps = [ ":bignum", "//:s2_testing_headers", "@abseil-cpp//absl/log:log_streamer", "@abseil-cpp//absl/random:bit_gen_ref", "@abseil-cpp//absl/strings:str_format", "@abseil-cpp//absl/strings:strings", "@googletest//:gtest_main", ] + select({ "//:use_openssl_setting": ["@openssl//:crypto"], "//conditions:default": ["@boringssl//:crypto"], }), ) cc_test( name = "exactfloat_test", srcs = ["exactfloat_test.cc"], deps = [ ":exactfloat", "//s2/testing:test_main", "//s2/util/math:vector", "@abseil-cpp//absl/base:core_headers", "@abseil-cpp//absl/base:no_destructor", "@abseil-cpp//absl/log:absl_check", "@abseil-cpp//absl/log:absl_log", "@abseil-cpp//absl/random", ], ) cc_test( name = "exactfloat_underflow_test", srcs = ["exactfloat_underflow_test.cc"], deps = [ ":exactfloat", "//s2/testing:test_main", "@abseil-cpp//absl/random:random", "@googletest//:gtest_main", ], ) src/s2/util/math/exactfloat/bignum.cc000066400000000000000000000641051524103652300200300ustar00rootroot00000000000000// Copyright 2025 Google LLC // Author: smcallis@google.com (Sean McAllister) // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #include "s2/util/math/exactfloat/bignum.h" #ifdef __x86_64__ #include #endif #include #include #include #include #include #include #include #include #include "absl/algorithm/container.h" #include "absl/base/nullability.h" #include "absl/log/absl_check.h" #include "absl/numeric/bits.h" #include "absl/numeric/int128.h" #include "absl/strings/string_view.h" #include "absl/types/span.h" namespace exactfloat_internal { // Number of bigits in smaller of the two operands before we fall back to simple // multiplication in the Karatsuba recursion. Determined empirically. static constexpr int kSimpleMulThreshold = 24; // Computes dst[i] = a[i]*b + c // // Returns the final carry, if any. inline Bigit MulWithCarry(absl::Span dst, absl::Span a, Bigit b, Bigit carry); // Compares magnitude magnitude of two bigit vectors, returning -1, 0, or +1. // // Magnitudes are compared lexicographically from the most significant bigit // to the least significant. int CmpAbs(absl::Span a, absl::Span b) { if (a.size() != b.size()) { return a.size() < b.size() ? -1 : +1; } for (int i = a.size() - 1; i >= 0; --i) { if (a[i] != b[i]) { return a[i] < b[i] ? -1 : +1; } } return 0; } int Bignum::Compare(const Bignum& b) const { if (is_negative() != b.is_negative()) { return is_negative() ? -1 : +1; } // Signs are equal, are they both zero? if (is_zero() && b.is_zero()) { return 0; } // Signs are equal and non-zero, compare magnitude. const int compare = CmpAbs(bigits_, b.bigits_); return is_negative() ? -compare : compare; } std::optional Bignum::FromString(absl::string_view s) { // A chunk is up to 19 decimal digits, which can always fit into a Bigit. static constexpr size_t kMaxChunkDigits = std::numeric_limits::digits10; // NOTE: We use a simple multiply-and-add (aka Horner's) method here for the // sake of simplicity. This isn't the fastest algorithm, being quadratic in // the number of chunks the input has. If we use divide and conquer approach // or an FFT based multiply we could probably make this ~O(n^1.5) or // semi-linear. // Precomputed powers of 10. static constexpr auto kPow10 = []() { std::array out = {1}; for (size_t i = 1; i < out.size(); ++i) { out[i] = 10 * out[i - 1]; } return out; }(); Bignum out; if (s.empty()) { return out; } out.bigits_.reserve((s.size() + kMaxChunkDigits - 1) / kMaxChunkDigits); bool negative = false; // Consume optional +/- at the front. const char* begin = s.data(); // std::from_chars needs pointers, not iterators if ((*begin == '+' || *begin == '-')) { negative = (s[0] == '-'); ++begin; } const char* end = s.data() + s.size(); while (begin < end) { size_t chunk_len = std::min(static_cast(end - begin), kMaxChunkDigits); Bigit chunk = 0; auto result = std::from_chars(begin, begin + chunk_len, chunk); if (result.ec != std::errc() || static_cast(result.ptr - begin) != chunk_len) { return std::nullopt; } begin += chunk_len; // Shift left by chunk_len digits and add the chunk to it. auto outspan = absl::MakeSpan(out.bigits_); Bigit carry = MulWithCarry(outspan, outspan, kPow10[chunk_len], chunk); if (carry) { out.bigits_.emplace_back(carry); } } out.negative_ = negative; out.Normalize(); return out; } int bit_width(const Bignum& a) { ABSL_DCHECK(a.bigits_.empty() || a.bigits_.back() != 0); if (a.is_zero()) { return 0; } // Bit width is the bits in the least significant bigits + bit width of // the most significant word. const int msw_width = absl::bit_width(a.bigits_.back()); const int lsw_width = (a.bigits_.size() - 1) * Bignum::kBigitBits; return msw_width + lsw_width; } int countr_zero(const Bignum& a) { int nzero = 0; for (Bigit bigit : a.bigits_) { if (bigit == 0) { nzero += Bignum::kBigitBits; } else { nzero += absl::countr_zero(bigit); break; } } return nzero; } bool Bignum::is_bit_set(int nbit) const { ABSL_DCHECK_GE(nbit, 0); const size_t digit = nbit / kBigitBits; const size_t shift = nbit % kBigitBits; if (digit >= bigits_.size()) { return false; } return ((bigits_[digit] >> shift) & 0x1) != 0; } Bignum Bignum::operator-() const { Bignum result = *this; result.negate(); return result; } Bignum& Bignum::operator<<=(int nbit) { ABSL_DCHECK_GE(nbit, 0); if (is_zero() || nbit == 0) { return *this; } const int nbigit = nbit / kBigitBits; const int nrem = nbit % kBigitBits; // First, handle the whole-bigit shift by inserting zeros. bigits_.insert(bigits_.begin(), nbigit, 0); // Then, handle the within-bigit shift, if any. if (nrem != 0) { Bigit carry = 0; for (size_t i = 0; i < bigits_.size(); ++i) { const Bigit old_val = bigits_[i]; bigits_[i] = (old_val << nrem) | carry; carry = old_val >> (kBigitBits - nrem); } if (carry) { bigits_.push_back(carry); } } return *this; } Bignum& Bignum::operator>>=(int nbit) { ABSL_DCHECK_GE(nbit, 0); if (is_zero() || nbit == 0) { return *this; } // Shifting by more than the bit width results in zero. if (nbit >= bit_width(*this)) { return set_zero(); } const int nbigit = nbit / kBigitBits; const int nrem = nbit % kBigitBits; // First, handle the whole-bigit shift by removing bigits. bigits_.erase(bigits_.begin(), bigits_.begin() + nbigit); // Then, handle the within-bigit shift, if any. if (nrem != 0) { Bigit carry = 0; for (int64_t i = static_cast(bigits_.size()) - 1; i >= 0; --i) { const Bigit old_val = bigits_[i]; bigits_[i] = (old_val >> nrem) | carry; carry = old_val << (kBigitBits - nrem); } } // Result might be smaller or zero, so normalize. Normalize(); return *this; } // Raise this value to the given power, which must be non-negative. Bignum Bignum::Pow(int32_t pow) const { ABSL_DCHECK_GE(pow, 0); // Anything to the zero-th power is 1 (including zero). if (pow == 0) { return Bignum(1); } if (is_zero()) { return Bignum(0); } // Core algorithm: Exponentiation by squaring. Bignum result(1); Bignum base = *this; // A mutable copy of the base. uint32_t upow = static_cast(pow); while (upow > 0) { if (upow & 1) { // If current exponent bit is 1, multiply into result. result *= base; } base *= base; upow >>= 1; } return result; } // Computes a + b + carry and updates the carry. inline Bigit AddBigit(Bigit a, Bigit b, Bigit* absl_nonnull carry) { // Compilers such as GCC and Clang are known to be terrible at generating good // code for long carry chains on Intel. Using the _addcarry_u64 intrinsic (which // maps to the add/adc instructions produces a tight series of add/adc/adc/adc // instructions, whereas writing the loop manually often generates many add/adc // pairs with spurious bit twiddling. // // Using the intrinsic here improves benchmarks by ~30% when summing larger // Bignums together. // // See this SO discussion for more information: // https://stackoverflow.com/questions/33690791 // // Godbolt link for comparison: // https://godbolt.org/z/cGnnfMbMn (no intrinsics) // https://godbolt.org/z/jnM1Y3Tjs (intrinsics) #ifdef __x86_64__ static_assert(sizeof(Bigit) == sizeof(unsigned long long)); Bigit out; *carry = _addcarry_u64(*carry, a, b, reinterpret_cast(&out)); return out; #else absl::uint128 sum = absl::uint128(a) + b + *carry; *carry = absl::Uint128High64(sum); return static_cast(sum); #endif } // Computes a - b - borrow and updates the borrow. // // NOTE: Borrow must be one or zero. inline Bigit SubBigit(Bigit a, Bigit b, Bigit* absl_nonnull borrow) { ABSL_DCHECK_LE(*borrow, Bigit(1)); // See notes in AddBigit on why using an intrinsic is the right choice here. #ifdef __x86_64__ Bigit out; *borrow = _subborrow_u64(static_cast(*borrow), a, b, reinterpret_cast(&out)); return out; #else Bigit diff = a - b - *borrow; *borrow = (a < b) || (*borrow && (a == b)); return diff; #endif } // Computes a * b + carry and updates the carry. inline Bigit MulBigit(Bigit a, Bigit b, Bigit* absl_nonnull carry) { absl::uint128 sum = absl::uint128(a) * b + *carry; *carry = absl::Uint128High64(sum); return static_cast(sum); } // Computes sum += a * b + carry and updates the carry. // // NOTE: Will not overflow even if a, b, and c are their maximum values. inline void MulAddBigit(Bigit* absl_nonnull sum, Bigit a, Bigit b, Bigit* absl_nonnull carry) { // Similar to the comment in AddBigit, and just for completeness, it's worth // noting that the "best" way to implement this is with the Intel MULX, ADCQ, // and ADOQ instructions (i.e. the _mulx_u64, _addcarry_u64, and // _addcarryx_u64 intrinsics), but GCC and Clang do not support _addcarryx_u64 // properly (and have no plans to do so). The issue is that gcc doesn't // support reasoning about separate dependency chains for the carry and // overflow flags, because all the flags are considered to be one // register. (The ADOX instructions were added specifically for this use case, // i.e. high-precision integer multiplies. They propagate carries using the // overflow flag rather than the carry flag, which lets you do two // extended-precision add operations in parallel without having them stomp on // each other's carry flags. ) absl::uint128 term = absl::uint128(a) * b + *carry + *sum; *carry = absl::Uint128High64(term); *sum = static_cast(term); } // Computes a += b in place. Returns the final carry (if any). // // A operand must be at least as large as B. When adding two same-sized values, // the result may overflow and be larger than either of them, in which case we // will return the final carry value. // // This allows a work flow like this: // Bigit carry = AddInPlace(a, b); // if (carry) { // a.bigits_.emplace_back(carry); // } // // Rather than having to expand A to B.bigits_.size() + 1, and popping off the // top bigit if it's unused (which is the most common case). ABSL_ATTRIBUTE_NOINLINE inline Bigit AddInPlace(absl::Span a, absl::Span b) { ABSL_DCHECK_GE(a.size(), b.size()); Bigit carry = 0; // Dispatch four at a time to help loop unrolling. size_t i = 0; while (i + 4 <= b.size()) { for (int j = 0; j < 4; ++j, ++i) { a[i] = AddBigit(a[i], b[i], &carry); } } // Finish remainder. for (; i < b.size(); ++i) { a[i] = AddBigit(a[i], b[i], &carry); } // Propagate carry through the rest of a. for (; carry && i < a.size(); ++i) { a[i] = AddBigit(a[i], 0, &carry); } return carry; } // Computes dst = a + b out of place. Returns the number of bigits actually // written into dst. // // NOTE: dst must be sized to be larger than max(a.size(), b.size()) + 1 (i.e. // it must be able to hold the carry bigit, if any. // // This allows for using a pre-allocated buffer to store the result of an // addition followed by trimming down to size: // // absl::Span out = arena.Alloc(std::max(a.size(), b.size()) + 1); // out = out.first(AddInto(out, a, b)); // // Which is used in the Karatsuba multiplication, where we don't have the option // to expand the allocate space on demand. inline size_t Add(absl::Span dst, absl::Span a, absl::Span b) { const size_t max_size = std::max(a.size(), b.size()); const size_t min_size = std::min(a.size(), b.size()); ABSL_DCHECK_GE(dst.size(), max_size + 1); // Add common parts. Bigit carry = 0; // Dispatch four at a time to help loop unrolling. size_t i = 0; while (i + 4 < min_size) { for (int j = 0; j < 4; ++j, ++i) { dst[i] = AddBigit(a[i], b[i], &carry); } } // Finish remainder of the parts common to A and B. for (; i < min_size; ++i) { dst[i] = AddBigit(a[i], b[i], &carry); } // Copy remaining digits from the longer operand and propagate carry. absl::Span longer = (a.size() > b.size()) ? a : b; // Dispatch four at a time for the remaining part. const size_t size = longer.size(); while (i + 4 < size) { for (int j = 0; j < 4; ++j, ++i) { dst[i] = AddBigit(longer[i], 0, &carry); } } // Propagate carry through the longer operand. for (; i < size; ++i) { dst[i] = AddBigit(longer[i], 0, &carry); } if (carry) { dst[i++] = carry; return max_size + 1; } return max_size; } // Computes a -= b. // // REQUIRES: |a| >= |b|. inline void SubInPlace(absl::Span a, absl::Span b) { ABSL_DCHECK_GE(a.size(), b.size()); ABSL_DCHECK_GE(CmpAbs(a, b), 0); Bigit borrow = 0; // Dispatch four at a time to help loop unrolling. size_t size = b.size(); size_t i = 0; while (i + 4 <= size) { for (int j = 0; j < 4; ++j, ++i) { a[i] = SubBigit(a[i], b[i], &borrow); } } // Finish remainder of subtraction. for (; i < size; ++i) { a[i] = SubBigit(a[i], b[i], &borrow); } // Propagate the borrow through a. for (; borrow && i < a.size(); ++i) { borrow = (a[i] == 0); a[i]--; } } // Computes a = b - a. // // NOTE: Requires |b| >= |a|. // // Since we write the result to a, but b is larger, a must be expanded with // enough leading zeros to fit the result. inline void SubReverseInPlace(absl::Span a, absl::Span b) { ABSL_DCHECK_GE(a.size(), b.size()); ABSL_DCHECK_GE(CmpAbs(b, a), 0); Bigit borrow = 0; // Dispatch four at a time to help loop unrolling. size_t size = a.size(); size_t i = 0; while (i + 4 <= size) { for (int j = 0; j < 4; ++j, ++i) { a[i] = SubBigit(b[i], a[i], &borrow); } } // Finish remainder. for (; i < size; ++i) { a[i] = SubBigit(b[i], a[i], &borrow); } } inline Bigit MulWithCarry(absl::Span dst, absl::Span a, Bigit b, Bigit carry) { ABSL_DCHECK_GE(dst.size(), a.size()); // Dispatch four at a time to help loop unrolling. size_t i = 0; while (i + 4 <= a.size()) { for (int j = 0; j < 4; ++j, ++i) { dst[i] = MulBigit(a[i], b, &carry); } } for (; i < a.size(); ++i) { dst[i] = MulBigit(a[i], b, &carry); } return carry; } // Computes sum[i] += a[i]*b in place. // // Returns the final carry, if any. inline Bigit MulAddInPlace(absl::Span sum, absl::Span a, Bigit b) { // Dispatch four at a time to help loop unrolling. Bigit carry = 0; size_t i = 0; while (i + 4 <= a.size()) { for (int j = 0; j < 4; ++j, ++i) { MulAddBigit(&sum[i], a[i], b, &carry); } } // Finish remainder. for (; i < a.size(); ++i) { MulAddBigit(&sum[i], a[i], b, &carry); } return carry; } // Implements the standard grade school long multiplication algorithm. The // output is computed by multiplying A by each digit of B and summing the // results as we go. This is a quadratic algorithm and only serves as the base // case for the recursive Karatsuba algorithm below. // // NOTE: out must be at least as large as the sums of the sizes of A and B. inline void MulQuadratic(absl::Span dst, absl::Span a, absl::Span b) { ABSL_DCHECK_GE(dst.size(), a.size() + b.size()); // Make sure A is the longer of the two arguments. if (a.size() < b.size()) { using std::swap; swap(a, b); } if (b.empty()) { absl::c_fill(dst, 0); return; } // Each call to MulAdd and MulAddInPlace only updates a.size() elements of out // so we manually set the carries as we go. We grab a span to the upper half // of out starting at a.size() to facilitate this. absl::Span upper = dst.subspan(a.size()); upper[0] = MulWithCarry(dst, a, b[0], 0); const size_t size = b.size(); size_t i = 1; for (; i < size; ++i) { upper[i] = MulAddInPlace(dst.subspan(i), a, b[i]); } // Finish zeroing out the upper half. for (; i < upper.size(); ++i) { upper[i] = 0; } } // Split a span into two contiguous spans of length at most a and b. // // If span.size() <= a, the second span is empty, otherwise the second span // has length at most b. If span.size() > a + b, then the two spans only cover // part of the input span. template inline std::pair, absl::Span> Split(absl::Span span, size_t a, size_t b) { if (a < span.size()) { return {span.subspan(0, a), span.subspan(a, b)}; } return {span.subspan(0, a), {}}; }; // A simple bump allocator to allow us to very efficiently allocate temporary // space when recursing in the Karatsuba multiply. The arena is pre-sized and // returns spans of memory via Alloc() which are then returned to the arena via // Release. // // NOTE: We use std::unique_ptr here instead of std::vector because we don't // want to initialize the memory unnecessarily and using std::vector without // resizing (and thus initializing) the container leads to false positives with // ASAN. class Arena { public: // TODO: Use make_unique_for_overwrite when on C++20. explicit Arena(size_t size) : size_(size), data_(new Bigit[size]) {} // Allocates a span of length n from the arena. absl::Span Alloc(size_t n) { ABSL_DCHECK_LE(used_ + n, size_); size_t start = used_; used_ += n; return absl::Span(data_.get() + start, n); } size_t Available() const { return size_ - used_; } size_t Used() const { return used_; } // Resets the arena to the given position which must be < Used(). void Reset(size_t to) { ABSL_DCHECK_LE(to, used_); used_ = to; } private: size_t size_ = 0; size_t used_ = 0; std::unique_ptr data_; }; // Returns the total arena size needed to multiply two number of a_size and // b_size bigits using the recursive Karatsuba implementation. This is enough // space for all the required recursive calls of KaratsubaMulRecursive. inline size_t ArenaSize(size_t a_size, size_t b_size) { // Each step of Karatsuba splits at: // N = (std::max(a.size() + b.size() + 1) / 2 // // We have to hold a total of 4*(N + 1) bigits as temporaries at each step. // // Simulate the recursion (log(n) steps) and compute the arena size. int peak = 0; while (std::min(a_size, b_size) > kSimpleMulThreshold) { int half = (std::max(a_size, b_size) + 1) / 2; int next = half + 1; peak += 4 * next; a_size = next; b_size = next; }; return peak; } // Recursive step in the Karatsuba multiplication. dst must be large enough to // hold the product of a and b (i.e. it must be at least as large as a.size() + // b.size()). The product is computed and stored in-place in dst. // // Additionally an arena must be provided for temporary storage for intermediate // products. The arena must have at least ArenaSize(a.size(), b.size()) space // available. inline void KaratsubaMulRecursive(absl::Span dst, absl::Span a, absl::Span b, Arena* absl_nonnull arena) { ABSL_DCHECK_GE(dst.size(), a.size() + b.size()); ABSL_DCHECK_GE(arena->Available(), ArenaSize(a.size(), b.size())); if (a.empty() || b.empty()) { absl::c_fill(dst, 0); return; } int arena_start = arena->Used(); // Karatsuba lets us represent two numbers of M bigits each, A and B, as: // // A = a1*10^(M/2) + a0 // B = b1*10^(M/2) + b0 // // Which we can multiply out: // AB = (a1*10^(M/2) + a0)*(b1*10^(M/2) + b0); // = a1*b1*10^M + (a1*b0 + a0*b1)*10^(M/2) + a0*b0 // = z2 * 10^M + z1*10^(M/2) + z0 // // Where: // z0 = a0*b0 // z1 = a1*b0 + a0*b1 // z2 = a1*b1 // // We can replace the multiplications in z1 by computing: // // z3 = (a0 + a1)*(b0 + b1) // // And noting z1 = z3 - z2 - z0 // // This lets us compute a 2M digit multiply with three M digit multiplies, // with those individual multiplies able to be recursively divided. // Fall back to long multiplication when we're small enough. if (std::min(a.size(), b.size()) <= kSimpleMulThreshold) { MulQuadratic(dst, a, b); return; } const size_t half = (std::max(a.size(), b.size()) + 1) / 2; // Split the inputs into contiguous subspans. auto [a0, a1] = Split(a, half, half); auto [b0, b1] = Split(b, half, half); // Make space to hold results in the output and multiply sub-terms. // z0 = a0 * b0 // z2 = a1 * b1 auto [z0, z2] = Split(dst, a0.size() + b0.size(), a1.size() + b1.size()); KaratsubaMulRecursive(z0, a0, b0, arena); KaratsubaMulRecursive(z2, a1, b1, arena); // Compute (a0 + a1) and (b0 + b1) // // If the upper terms are zero we can just re-use the terms we have, otherwise // we compute the sum and pop off the MSB bigit if no carry occurred. absl::Span asum = a0; if (!a1.empty()) { absl::Span tmp = arena->Alloc(half + 1); asum = tmp.first(Add(tmp, a0, a1)); } absl::Span bsum = b0; if (!b1.empty()) { absl::Span tmp = arena->Alloc(half + 1); bsum = tmp.first(Add(tmp, b0, b1)); } // Compute z1 = asum*bsum - z0 - z2 = (a0 + a1)*(b0 + b1) - z0 - z2 absl::Span z1 = arena->Alloc(asum.size() + bsum.size()); // Compute asum * bsum into the beginning of z1 KaratsubaMulRecursive(z1, asum, bsum, arena); // NOTE: (a0 + a1) * (b0 + b1) >= a0*b0 + a1*b1 so this never underflows. SubInPlace(z1, z0); if (!a1.empty() && !b1.empty()) { SubInPlace(z1, z2); } // We need to add z1*10^half, which we can do by simply adding z1 at a shifted // position in the output. absl::Span dst_z1 = dst.subspan(half); // Although the value of z1 is guaranteed to fit in the available space of // dst, it may have one or more high-order zero bigits because it was sized // conservatively to hold the intermediate result (asum * bsum). We trim these // leading zeros if necessary to ensure that the Add() operation below does // not attempt to write zero bigits past the end of dst. AddInPlace(dst_z1, z1.first(std::min(z1.size(), dst_z1.size()))); // Release temporary memory we used. arena->Reset(arena_start); } // Multiplies two unsigned bigit vectors together using Karatsuba's algorithm. // // This algorithm recursively subdivides the inputs until one or both is below // some threshold, and then falls back to standard long multiplication. void KaratsubaMul(absl::Span dst, absl::Span a, absl::Span b) { ABSL_DCHECK_GE(dst.size(), a.size() + b.size()); if (a.empty() || b.empty()) { absl::c_fill(dst, 0); return; } Arena arena(ArenaSize(a.size(), b.size())); KaratsubaMulRecursive(dst, a, b, &arena); } Bignum& Bignum::operator+=(const Bignum& b) { if (b.is_zero()) { return *this; } if (is_zero()) { *this = b; return *this; } if (is_negative() == b.is_negative()) { // Same sign: // +|a| + +|b| == +(|a| + |b|) // -|a| + -|b| == -(|a| + |b|) // // So we can just sum magnitudes, final sign is the same as A. bigits_.resize(std::max(bigits_.size(), b.bigits_.size()), 0); Bigit carry = AddInPlace(absl::MakeSpan(bigits_), b.bigits_); if (carry) { bigits_.emplace_back(carry); } } else { // We know the signs are different, so there's two options: // -|a| + +|b| = ?(|b| - |a|) // +|a| + -|b| = ?(|a| - |b|) // // With the final sign being dependent on how |a| and |b| relate. if (CmpAbs(bigits_, b.bigits_) >= 0) { // |a| >= |b| // -|a| + +|b| --> -(|a| - |b|) // +|a| + -|b| --> +(|a| - |b|) // // So we can subtract magnitudes, final sign is the same as A. SubInPlace(absl::MakeSpan(bigits_), b.bigits_); } else { // |a| < |b| // -|a| + +|b| --> +(|b| - |a|) // +|a| + -|b| --> -(|b| - |a|) // // So we can compute |b| - |a| and the final sign is the same as B. bigits_.resize(b.bigits_.size()); SubReverseInPlace(absl::MakeSpan(bigits_), b.bigits_); negative_ = b.is_negative(); } } Normalize(); return *this; } Bignum& Bignum::operator-=(const Bignum& b) { if (this == &b) { set_zero(); return *this; } // Compute -(-a + b) == a - b negate(); *this += b; negate(); return *this; } Bignum& Bignum::operator*=(const Bignum& b) { if (is_zero() || b.is_zero()) { return set_zero(); } // Result is only negative if signs are different. const bool negative = (is_negative() != b.is_negative()); // Fast path for single-bigit multiplication. if (bigits_.size() == 1 && b.bigits_.size() == 1) { absl::uint128 prod = absl::uint128(bigits_[0]) * b.bigits_[0]; const uint64_t lo = absl::Uint128Low64(prod); const uint64_t hi = absl::Uint128High64(prod); if (hi == 0) { bigits_ = {lo}; } else { bigits_ = {lo, hi}; } set_negative(negative); return *this; } // Use Karatsuba multiplication. // If the inputs are small enough this will just do long multiplication. BigitVector result; result.resize(bigits_.size() + b.bigits_.size()); KaratsubaMul(absl::MakeSpan(result), bigits_, b.bigits_); bigits_ = std::move(result); negative_ = negative; Normalize(); return *this; } } // namespace exactfloat_internal src/s2/util/math/exactfloat/bignum.h000066400000000000000000000272571524103652300177010ustar00rootroot00000000000000// Copyright 2025 Google LLC // Author: smcallis@google.com (Sean McAllister) // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #ifndef S2_UTIL_MATH_EXACTFLOAT_BIGNUM_H_ #define S2_UTIL_MATH_EXACTFLOAT_BIGNUM_H_ #include #include #include #include #include #include "absl/algorithm/container.h" #include "absl/base/attributes.h" #include "absl/container/inlined_vector.h" #include "absl/log/absl_check.h" #include "absl/numeric/bits.h" #include "absl/numeric/int128.h" #include "absl/strings/ascii.h" #include "absl/strings/str_format.h" namespace exactfloat_internal { // A digit of a bignum. A contraction of "big digit" (rhymes with the latter). using Bigit = uint64_t; // A class to support arithmetic on large, arbitrary precision integers. // // Large integers are represented as an array of uint64_t values. class Bignum { public: // The most common use of ExactFloat involves evaluating a 3x3 determinant to // determine whether 3 points are oriented clockwise or counter-clockwise. // // The typical number of mantissa bits in the result is probably about 170, so // we allocate 4 bigits (256 bits) inline. using BigitVector = absl::InlinedVector; static constexpr int kBigitBits = std::numeric_limits::digits; Bignum() = default; // Constructs a bignum from an integral value (signed or unsigned). template ::is_integer>> explicit Bignum(T value); //-------------------------------------- // String formatting and parsing. //-------------------------------------- // Constructs a bignum from an ASCII string containing decimal digits. // // The input string must only have an optional leading +/- and decimal digits. // Any other characters will yield std::nullopt. static std::optional FromString(absl::string_view s); // Formats the bignum as a decimal integer into an abseil sink. template friend void AbslStringify(Sink& sink, const Bignum& b); friend std::ostream& operator<<(std::ostream& os, const Bignum& b) { return os << absl::StrFormat("%v", b); } friend std::ostream& operator<<(std::ostream& os, const std::optional& b) { if (!b) { return os << "[nullopt]"; } return os << *b; } //-------------------------------------- // Casting and coercion. //-------------------------------------- // Returns true if bignum can be stored in T without truncation or overflow. template >> bool FitsIn() const; // Cast to an integral type T unconditionally. Use FitsIn() or // ConvertTo to perform conversion with bounds checking. template >> T Cast() const; // Casts the value to the given type if it fits, otherwise std::nullopt. template >> std::optional ConvertTo() const { if (!FitsIn()) { return std::nullopt; } return Cast(); } //-------------------------------------- // General accessors. //-------------------------------------- // Returns the number of bits required for the magnitude of the value. // // Named to match std::bit_width. friend int bit_width(const Bignum& a); // Returns the number of consecutive 0 bits in the value, starting from the // least significant bit. // // Named to match std::countr_zero. friend int countr_zero(const Bignum& a); // Returns true if the n-th bit of the number's magnitude is 1. bool is_bit_set(int nbit) const; // Clears this bignum and sets it to zero. Bignum& set_zero() { negative_ = false; bigits_.clear(); return *this; } // Sets the negative flag on the value. If the value is zero, has no effect. Bignum& set_negative(bool negative = true) { negative_ = !bigits_.empty() && negative; return *this; } // Returns true if the number is zero. bool is_zero() const { return bigits_.empty(); } // Returns true if the number is less than zero. bool is_negative() const { return negative_; } // Returns true if the number is odd (least significant bit is 1). bool is_odd() const { return is_bit_set(0); } // Returns true if the number is even (least significant bit is 0). bool is_even() const { return !is_odd(); } //-------------------------------------- // Comparisons. //-------------------------------------- bool operator==(const Bignum& b) const { return negative_ == b.negative_ && bigits_ == b.bigits_; } bool operator!=(const Bignum& b) const { return !(*this == b); } bool operator<(const Bignum& b) const { return Compare(b) < 0; } bool operator<=(const Bignum& b) const { return Compare(b) <= 0; } bool operator>(const Bignum& b) const { return Compare(b) > 0; } bool operator>=(const Bignum& b) const { return Compare(b) >= 0; } //-------------------------------------- // Arithmetic operators. //-------------------------------------- Bignum operator+() const { return *this; } Bignum operator-() const; // Raise this value to the given power, which must be non-negative. Bignum Pow(int32_t pow) const; Bignum& operator+=(const Bignum& b); Bignum& operator-=(const Bignum& b); Bignum& operator*=(const Bignum& b); Bignum& operator<<=(int nbit); Bignum& operator>>=(int nbit); friend Bignum operator+(Bignum a, const Bignum& b) { return a += b; } friend Bignum operator-(Bignum a, const Bignum& b) { return a -= b; } friend Bignum operator*(Bignum a, const Bignum& b) { return a *= b; } friend Bignum operator<<(Bignum a, int nbit) { return a <<= nbit; } friend Bignum operator>>(Bignum a, int nbit) { return a >>= nbit; } // Negates this bignum in place. void negate() { negative_ = !negative_; if (bigits_.empty()) { negative_ = false; } } // Compares to another bignum, returning -1, 0, +1. int Compare(const Bignum& b) const; private: // Constructs a Bignum from bigits and an optional sign bit. explicit Bignum(BigitVector bigits, bool negative = false) : bigits_(std::move(bigits)), negative_(negative) { Normalize(); } // Drop leading zero bigits, and ensure sign is positive if result is zero. void Normalize() { while (!bigits_.empty() && bigits_.back() == 0) { bigits_.pop_back(); } if (bigits_.empty()) { negative_ = false; } } // We store bignums in sign-magnitude form. bigits_ contains the individual // 64-bit digits of the bignum, stored in little-endian order. If bigits_ is // non-empty, then the last element must be non-zero and when it is empty // (representing a zero value), negative_ must be false. BigitVector bigits_; bool negative_ = false; }; //////////////////////////////////////////////////////////////////////////////// // Implementation Details //////////////////////////////////////////////////////////////////////////////// // Constructs a bignum from an integral value (signed or unsigned). template Bignum::Bignum(T value) { using UT = std::make_unsigned_t; if (value == 0) { return; } negative_ = false; if constexpr (std::is_signed_v) { // Put into constexpr if to avoid warnings when T is unsigned. negative_ = (value < 0); } // Get magnitude of value, handle minimum value of T cleanly. UT mag = static_cast(value); if constexpr (std::is_signed_v) { if (value < 0) { mag = UT(0) - mag; } } // Pack the magnitude into bigits. if constexpr (std::numeric_limits::digits <= kBigitBits) { bigits_.push_back(static_cast(mag)); } else { while (mag) { bigits_.push_back(static_cast(mag)); mag >>= kBigitBits; } } } // Formats the bignum as a decimal integer into an abseil sink. template void AbslStringify(Sink& sink, const Bignum& b) { if (b.is_zero()) { sink.Append("0"); return; } // Sign if (b.is_negative()) { sink.Append("-"); } // Work on a copy of the magnitude. Bignum copy = b; copy.negative_ = false; // 10**19 is the largest power of 10 that fits in 64-bits. So we can // repeatedly divide and modulo the bignum to get uint64_t values we can // format as 19 decimal digits. static_assert(sizeof(Bigit) * 8 == 64); static constexpr uint64_t kChunkDivisor = 10'000'000'000'000'000'000u; Bignum::BigitVector chunks; while (!copy.is_zero()) { absl::uint128 rem = 0; for (int i = static_cast(copy.bigits_.size()) - 1; i >= 0; --i) { absl::uint128 acc = (rem << 64) + copy.bigits_[i]; Bigit quot = static_cast(acc / kChunkDivisor); rem = acc - absl::uint128(quot) * kChunkDivisor; copy.bigits_[i] = quot; } copy.Normalize(); chunks.push_back(static_cast(rem)); } ABSL_DCHECK(!chunks.empty()); // Emit most significant chunk without zero padding. absl::Format(&sink, "%d", chunks.back()); // Emit remaining chunks as fixed-width 19-digit zero-padded blocks. for (int i = static_cast(chunks.size()) - 2; i >= 0; --i) { absl::Format(&sink, "%019d", chunks[i]); } } template inline bool Bignum::FitsIn() const { using UT = std::make_unsigned_t; if (is_zero()) { return true; } // Maximum number of bits that could fit in the output type. constexpr int kTBitWidth = std::numeric_limits::digits; constexpr int kMaxBigits = (kTBitWidth + (kBigitBits - 1)) / kBigitBits; // Fast reject if the bignum couldn't conceivably fit. if (bigits_.size() > kMaxBigits) { return false; } // Unsigned type T can hold the value iff the value is non-negative and // the bitwidth is <= the maximum bit width of the type. if constexpr (!std::is_signed_v) { if (is_negative()) { return false; } return bit_width(*this) <= kTBitWidth; } // T is signed and our bignum isn't zero. ABSL_DCHECK(std::is_signed_v && !is_zero()); if (is_negative()) { // Magnitude must fit in negative value. If the value is negative and // the same bit width as the output type, the only valid value is // -2^(k-1). if (bit_width(*this) == kTBitWidth) { return countr_zero(*this) == kTBitWidth - 1; } return bit_width(*this) < kTBitWidth; } else /* positive */ { return bit_width(*this) <= (kTBitWidth - 1); } } template T Bignum::Cast() const { using UT = std::make_unsigned_t; constexpr int kTBitWidth = std::numeric_limits::digits; if (bigits_.empty()) { return 0; } // T fits in a Bigit, so just cast to truncate. UT residue = 0; if (kTBitWidth <= kBigitBits) { residue = static_cast(bigits_[0]); } else { ABSL_DCHECK_EQ(kTBitWidth % kBigitBits, 0); for (int i = 0; i < kTBitWidth / kBigitBits; ++i) { UT chunk = static_cast(bigits_[i]); residue |= chunk << (i * kBigitBits); } } // Compute two's complement of the residue if value is negative. if (is_negative()) { residue = UT(0) - residue; } return static_cast(residue); } } // namespace exactfloat_internal #endif // S2_UTIL_MATH_EXACTFLOAT_BIGNUM_H_ src/s2/util/math/exactfloat/bignum_test.cc000066400000000000000000001150241524103652300210640ustar00rootroot00000000000000// Copyright 2025 Google LLC // Author: smcallis@google.com (Sean McAllister) // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #include "s2/util/math/exactfloat/bignum.h" #include #include #include #include #include #include #include // TODO: remove once benchmarks are available #if 0 #include "benchmark/benchmark.h" #endif #include #include #include #include "absl/log/log_streamer.h" #include "absl/random/bit_gen_ref.h" #include "absl/random/random.h" #include "absl/strings/str_cat.h" #include "absl/strings/str_format.h" #include "absl/strings/string_view.h" #include "s2/s2testing.h" namespace exactfloat_internal { using ::testing::TestWithParam; constexpr uint64_t kU8max = std::numeric_limits::max(); constexpr uint64_t kU16max = std::numeric_limits::max(); constexpr uint64_t kU32max = std::numeric_limits::max(); constexpr uint64_t kU64max = std::numeric_limits::max(); constexpr int64_t kI8max = std::numeric_limits::max(); constexpr int64_t kI16max = std::numeric_limits::max(); constexpr int64_t kI32max = std::numeric_limits::max(); constexpr int64_t kI64max = std::numeric_limits::max(); constexpr int64_t kI8min = std::numeric_limits::min(); constexpr int64_t kI16min = std::numeric_limits::min(); constexpr int64_t kI32min = std::numeric_limits::min(); constexpr int64_t kI64min = std::numeric_limits::min(); // To reduce duplication. inline auto Bn(absl::string_view str) { return Bignum::FromString(str); }; TEST(BignumTest, ZeroInputsNormalizeToZero) { EXPECT_EQ(Bn(""), Bignum(0)); EXPECT_EQ(Bn("+"), Bignum(0)); EXPECT_EQ(Bn("-"), Bignum(0)); EXPECT_EQ(Bn("0"), Bignum(0)); EXPECT_EQ(Bn("-0"), Bignum(0)); EXPECT_EQ(Bn("000000"), Bignum(0)); EXPECT_EQ(Bn("-000000"), Bignum(0)); EXPECT_EQ(Bn("-00000000000000000000"), Bignum(0)); EXPECT_EQ(Bn("+00000000000000000000"), Bignum(0)); } TEST(BignumTest, BasicSmallNumbers) { EXPECT_EQ(Bn("42"), Bignum(42)); EXPECT_EQ(Bn("-17"), Bignum(-17)); EXPECT_EQ(Bn("+123"), Bignum(123)); } TEST(BignumTest, LeadingZeros) { EXPECT_EQ(Bn("0000042"), Bignum(42)); EXPECT_EQ(Bn("-00017"), Bignum(-17)); EXPECT_EQ(Bn("+00007"), Bignum(7)); // Larger bignums. // 10^19 and 10^19 - 1, near chunk boundaries. EXPECT_EQ(Bn("100000000000000000"), Bn("000100000000000000000")); EXPECT_EQ(Bn("99999999999999999"), Bn("000099999999999999999")); // 2^64 - 1 cross-check against integral constructor. EXPECT_EQ(Bn("18446744073709551615"), Bignum(18446744073709551615ull)); // 2^64 cross-check with leading zeros variant via string constructor. EXPECT_EQ(Bn("18446744073709551616"), Bn("00018446744073709551616")); EXPECT_EQ(Bn("-18446744073709551616"), Bn("-00018446744073709551616")); // Multi-digit bignums. // 2^80 EXPECT_EQ(Bn("1208925819614629174706176"), Bn("0001208925819614629174706176")); EXPECT_EQ(Bn("-1208925819614629174706176"), Bn("-0001208925819614629174706176")); // 2^128 EXPECT_EQ(Bn("340282366920938463463374607431768211456"), Bn("000340282366920938463463374607431768211456")); EXPECT_EQ(Bn("-340282366920938463463374607431768211456"), Bn("-000340282366920938463463374607431768211456")); } TEST(BignumTest, MultipleSignsBeforeDigitsCausesFailure) { EXPECT_EQ(Bn("++123"), std::nullopt); EXPECT_EQ(Bn("--42"), std::nullopt); EXPECT_EQ(Bn("+-9"), std::nullopt); EXPECT_EQ(Bn("-+9"), std::nullopt); } TEST(BignumTest, SignInWrongPlaceCausesFailure) { EXPECT_EQ(Bn("123-"), std::nullopt); EXPECT_EQ(Bn("456+"), std::nullopt); EXPECT_EQ(Bn("-789+"), std::nullopt); EXPECT_EQ(Bn("+314-"), std::nullopt); } TEST(BignumTest, ZeroAlwaysFitsIn) { const Bignum zero(0); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); EXPECT_TRUE(zero.FitsIn()); } TEST(BignumTest, ZeroAlwaysCastsToZero) { Bignum zero; EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); EXPECT_EQ(zero.Cast(), 0); } TEST(BignumTest, NegativeOnlyFitsInSigned) { const Bignum small_neg(-1); EXPECT_FALSE(small_neg.FitsIn()); EXPECT_FALSE(small_neg.FitsIn()); EXPECT_FALSE(small_neg.FitsIn()); EXPECT_FALSE(small_neg.FitsIn()); EXPECT_TRUE(small_neg.FitsIn()); EXPECT_TRUE(small_neg.FitsIn()); EXPECT_TRUE(small_neg.FitsIn()); EXPECT_TRUE(small_neg.FitsIn()); } TEST(BignumTest, FitsInUnsignedBoundsChecks) { const Bignum bn_u8max(kU8max); const Bignum bn_u8over(kU8max + 1); EXPECT_TRUE(bn_u8max.FitsIn()); EXPECT_TRUE(bn_u8max.FitsIn()); EXPECT_TRUE(bn_u8max.FitsIn()); EXPECT_FALSE(bn_u8over.FitsIn()); EXPECT_TRUE(bn_u8over.FitsIn()); EXPECT_TRUE(bn_u8over.FitsIn()); const Bignum bn_u16max(kU16max); const Bignum bn_u16over(kU16max + 1); EXPECT_FALSE(bn_u16max.FitsIn()); EXPECT_TRUE(bn_u16max.FitsIn()); EXPECT_TRUE(bn_u16max.FitsIn()); EXPECT_FALSE(bn_u16over.FitsIn()); EXPECT_FALSE(bn_u16over.FitsIn()); EXPECT_TRUE(bn_u16over.FitsIn()); const Bignum bn_u32max(kU32max); const Bignum bn_u32over(kU32max + 1); EXPECT_FALSE(bn_u32max.FitsIn()); EXPECT_FALSE(bn_u32max.FitsIn()); EXPECT_TRUE(bn_u32max.FitsIn()); EXPECT_FALSE(bn_u32over.FitsIn()); EXPECT_FALSE(bn_u32over.FitsIn()); EXPECT_FALSE(bn_u32over.FitsIn()); const Bignum bn_u64max(kU64max); EXPECT_TRUE(bn_u64max.FitsIn()); // 2^64, need to use string constructor. Bignum bn0 = *Bn("18446744073709551616"); EXPECT_FALSE(bn0.FitsIn()); } TEST(BignumTest, FitsInSignedBoundsChecks) { const Bignum bn_i8max(kI8max); const Bignum bn_i8over(kI8max + 1); EXPECT_TRUE(bn_i8max.FitsIn()); EXPECT_TRUE(bn_i8max.FitsIn()); EXPECT_TRUE(bn_i8max.FitsIn()); EXPECT_FALSE(bn_i8over.FitsIn()); EXPECT_TRUE(bn_i8over.FitsIn()); EXPECT_TRUE(bn_i8over.FitsIn()); const Bignum bn_i16max(kI16max); const Bignum bn_i16over(kI16max + 1); EXPECT_FALSE(bn_i16max.FitsIn()); EXPECT_TRUE(bn_i16max.FitsIn()); EXPECT_TRUE(bn_i16max.FitsIn()); EXPECT_FALSE(bn_i16over.FitsIn()); EXPECT_FALSE(bn_i16over.FitsIn()); EXPECT_TRUE(bn_i16over.FitsIn()); const Bignum bn_i32max(kI32max); const Bignum bn_i32over(kI32max + 1); EXPECT_FALSE(bn_i32max.FitsIn()); EXPECT_FALSE(bn_i32max.FitsIn()); EXPECT_TRUE(bn_i32max.FitsIn()); EXPECT_FALSE(bn_i32over.FitsIn()); EXPECT_FALSE(bn_i32over.FitsIn()); EXPECT_FALSE(bn_i32over.FitsIn()); Bignum bn_i64max(kI64max); EXPECT_TRUE(bn_i64max.FitsIn()); // 2^63, need to use string constructor. Bignum bn0 = *Bn("9223372036854775808"); EXPECT_FALSE(bn0.FitsIn()); const Bignum bn_i8min(kI8min); const Bignum bn_i8under(kI8min - 1); EXPECT_TRUE(bn_i8min.FitsIn()); EXPECT_TRUE(bn_i8min.FitsIn()); EXPECT_TRUE(bn_i8min.FitsIn()); EXPECT_FALSE(bn_i8under.FitsIn()); EXPECT_TRUE(bn_i8under.FitsIn()); EXPECT_TRUE(bn_i8under.FitsIn()); const Bignum bn_i16min(kI16min); const Bignum bn_i16under(kI16min - 1); EXPECT_FALSE(bn_i16min.FitsIn()); EXPECT_TRUE(bn_i16min.FitsIn()); EXPECT_TRUE(bn_i16min.FitsIn()); EXPECT_FALSE(bn_i16under.FitsIn()); EXPECT_FALSE(bn_i16under.FitsIn()); EXPECT_TRUE(bn_i16under.FitsIn()); const Bignum bn_i32min(kI32min); const Bignum bn_i32under(kI32min - 1); EXPECT_FALSE(bn_i32min.FitsIn()); EXPECT_FALSE(bn_i32min.FitsIn()); EXPECT_TRUE(bn_i32min.FitsIn()); EXPECT_FALSE(bn_i32under.FitsIn()); EXPECT_FALSE(bn_i32under.FitsIn()); EXPECT_FALSE(bn_i32under.FitsIn()); Bignum bn_i64min(kI64min); EXPECT_TRUE(bn_i64min.FitsIn()); } TEST(BignumTest, FitsInBasicSanityChecks) { Bignum pos42(42); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); EXPECT_TRUE(pos42.FitsIn()); Bignum neg42(-42); EXPECT_TRUE(neg42.FitsIn()); EXPECT_FALSE(neg42.FitsIn()); EXPECT_TRUE(neg42.FitsIn()); EXPECT_FALSE(neg42.FitsIn()); EXPECT_TRUE(neg42.FitsIn()); EXPECT_FALSE(neg42.FitsIn()); EXPECT_TRUE(neg42.FitsIn()); EXPECT_FALSE(neg42.FitsIn()); } TEST(BignumTest, UnsignedCasting) { EXPECT_EQ(Bignum(300).Cast(), static_cast(300)); // Negative to unsigned -> maximum value. Bignum bn1(-1); EXPECT_EQ(bn1.Cast(), std::numeric_limits::max()); EXPECT_EQ(bn1.Cast(), std::numeric_limits::max()); EXPECT_EQ(bn1.Cast(), std::numeric_limits::max()); EXPECT_EQ(bn1.Cast(), std::numeric_limits::max()); // Big values via decimal: 2^64, 2^128-1, 2^128 Bignum bn2 = *Bn("18446744073709551616"); EXPECT_EQ(bn2.Cast(), 0); // 2^128 - 1 -> lower 64 bits = 2^64 - 1 Bignum bn3 = *Bn("340282366920938463463374607431768211455"); EXPECT_EQ(bn3.Cast(), std::numeric_limits::max()); // 2^128 -> lower 64 bits = 0 Bignum bn4 = *Bn("340282366920938463463374607431768211456"); EXPECT_EQ(bn4.Cast(), 0); } TEST(BignumTest, SignedCasting) { // In-range positives stay the same. Bignum bn0(127); EXPECT_EQ(bn0.Cast(), 127); // Positive overflow wraps into negative range. Bignum bn1(128); EXPECT_EQ(bn1.Cast(), -128); // In-range negatives stay the same. Bignum bn2(-128); EXPECT_EQ(bn2.Cast(), -128); // Negative overflow wraps into positive range. Bignum bn3(-129); EXPECT_EQ(bn3.Cast(), 127); // +2^63 over to -2^63 in signed int64. Bignum bn4 = *Bn("9223372036854775808"); EXPECT_EQ(bn4.Cast(), std::numeric_limits::min()); // +2^64 - 1 casts to -1. Bignum bn5 = *Bn("18446744073709551615"); EXPECT_EQ(bn5.Cast(), -1); // -(2^63) - 1 casts to 2^63 - 3 Bignum bn6 = *Bn("-9223372036854775809"); EXPECT_EQ(bn6.Cast(), std::numeric_limits::max()); } TEST(BignumTest, CastingLargeResidues) { // 2^80 + 0x1234 -> low 64 bits should be 0x1234. Bignum bn0 = *Bn("1208925819614629174710836"); EXPECT_EQ(bn0.Cast(), 0x1234); EXPECT_EQ(bn0.Cast(), 0x1234); // -(2^80 + 1) -> low 64 bits = 0xFFFFFFFFFFFFFFFF; signed = -1 Bignum bn1 = *Bn("-1208925819614629174706177"); EXPECT_EQ(bn1.Cast(), std::numeric_limits::max()); EXPECT_EQ(bn1.Cast(), -1); } TEST(BignumTest, UnaryOperators) { EXPECT_EQ(+Bignum(0), Bignum(0)); EXPECT_EQ(-Bignum(0), Bignum(0)); EXPECT_EQ(+Bignum(+42), Bignum(+42)); EXPECT_EQ(+Bignum(-42), Bignum(-42)); EXPECT_EQ(-Bignum(+42), Bignum(-42)); EXPECT_EQ(-Bignum(-17), Bignum(+17)); } TEST(BignumTest, Addition) { // Basic combinations of signs EXPECT_EQ(Bignum(+5) + Bignum(+3), Bignum(+8)); EXPECT_EQ(Bignum(-5) + Bignum(-3), Bignum(-8)); EXPECT_EQ(Bignum(+5) + Bignum(-3), Bignum(+2)); EXPECT_EQ(Bignum(-5) + Bignum(+3), Bignum(-2)); // Identity and additive inverse EXPECT_EQ(Bignum(42) + Bignum(0), Bignum(42)); EXPECT_EQ(Bignum(0) + Bignum(42), Bignum(42)); EXPECT_EQ(Bignum(5) + Bignum(-5), Bignum(0)); // Carry propagation const auto bn_u64max = Bignum(kU64max); EXPECT_EQ(bn_u64max + Bignum(1), *Bn("18446744073709551616")); EXPECT_EQ(bn_u64max + bn_u64max, *Bn("36893488147419103230")); // Aliasing (x += x) Bignum a = bn_u64max; a += a; EXPECT_EQ(a, *Bn("36893488147419103230")); } TEST(BignumTest, Subtraction) { // Basic combinations of signs EXPECT_EQ(Bignum(+5) - Bignum(+3), Bignum(+2)); EXPECT_EQ(Bignum(+3) - Bignum(+5), Bignum(-2)); EXPECT_EQ(Bignum(-5) - Bignum(-3), Bignum(-2)); EXPECT_EQ(Bignum(+5) - Bignum(-3), Bignum(+8)); EXPECT_EQ(Bignum(-5) - Bignum(+3), Bignum(-8)); // Identity and subtracting to zero EXPECT_EQ(Bignum(42) - Bignum(0), Bignum(42)); EXPECT_EQ(Bignum(0) - Bignum(42), Bignum(-42)); EXPECT_EQ(Bignum(42) - Bignum(42), Bignum(0)); // Borrow propagation const auto bn_u64max = Bignum(kU64max); const auto two_pow_64 = *Bn("18446744073709551616"); EXPECT_EQ(two_pow_64 - Bignum(1), bn_u64max); // Aliasing (x -= x) Bignum a(100); a -= a; EXPECT_EQ(a, Bignum(0)); } TEST(BignumTest, MixedOperations) { Bignum a(10), b(20), c(-5); EXPECT_EQ((a + b) - a, b); EXPECT_EQ((b - a) + a, b); EXPECT_EQ(a + c, Bignum(5)); EXPECT_EQ(c - a, Bignum(-15)); } TEST(BignumTest, LargeNumberArithmetic) { const auto two_pow_128_minus_1 = *Bn("340282366920938463463374607431768211455"); const auto two_pow_128 = *Bn("340282366920938463463374607431768211456"); const auto two_pow_64 = *Bn("18446744073709551616"); // Test multi-bigit carry propagation: (2^128 - 1) + 1 = 2^128 EXPECT_EQ(two_pow_128_minus_1 + Bignum(1), two_pow_128); // Test multi-bigit borrow propagation: 2^128 - 1 = (2^128 - 1) EXPECT_EQ(two_pow_128 - Bignum(1), two_pow_128_minus_1); // Subtraction resulting in a sign change with large numbers. const auto neg_two_pow_128_minus_1 = *Bn("-340282366920938463463374607431768211455"); EXPECT_EQ(Bignum(1) - two_pow_128, neg_two_pow_128_minus_1); // Addition of large numbers with different signs (triggers subtraction). EXPECT_EQ(two_pow_128 + Bignum(-1), two_pow_128_minus_1); // Subtraction of large numbers with different signs (triggers addition). EXPECT_EQ(two_pow_128_minus_1 - Bignum(-1), two_pow_128); // Add two different large positive numbers: 2^128 + 2^64 const auto sum_128_64 = *Bn("340282366920938463481821351505477763072"); EXPECT_EQ(two_pow_128 + two_pow_64, sum_128_64); // Subtract two different large positive numbers: 2^128 - 2^64 const auto diff_128_64 = *Bn("340282366920938463444927863358058659840"); EXPECT_EQ(two_pow_128 - two_pow_64, diff_128_64); } TEST(BignumTest, LeftShift) { EXPECT_EQ((Bignum(1) << 0), Bignum(1)); EXPECT_EQ((Bignum(1) << 1), Bignum(2)); EXPECT_EQ((Bignum(1) << 63), *Bn("9223372036854775808")); EXPECT_EQ((Bignum(1) << 64), *Bn("18446744073709551616")); EXPECT_EQ((Bignum(-1) << 64), *Bn("-18446744073709551616")); const auto bn_u64max = Bignum(kU64max); const auto two_pow_128_minus_two_pow_64 = *Bn("340282366920938463444927863358058659840"); EXPECT_EQ((bn_u64max << 64), two_pow_128_minus_two_pow_64); Bignum a(5); a <<= 2; EXPECT_EQ(a, Bignum(20)); // Shifting zero or by zero amount. EXPECT_EQ((Bignum(0) << 100), Bignum(0)); EXPECT_EQ((Bignum(123) << 0), Bignum(123)); } TEST(BignumTest, RightShift) { EXPECT_EQ((Bignum(8) >> 0), Bignum(8)); EXPECT_EQ((Bignum(8) >> 3), Bignum(1)); EXPECT_EQ((Bignum(8) >> 4), Bignum(0)); EXPECT_EQ((Bignum(7) >> 2), Bignum(1)); EXPECT_EQ((Bignum(-7) >> 2), Bignum(-1)); const auto two_pow_64 = *Bn("18446744073709551616"); EXPECT_EQ((two_pow_64 >> 1), *Bn("9223372036854775808")); EXPECT_EQ((two_pow_64 >> 64), Bignum(1)); EXPECT_EQ((two_pow_64 >> 65), Bignum(0)); const auto u64max = Bignum(std::numeric_limits::max()); const auto two_pow_128_minus_1 = *Bn("340282366920938463463374607431768211455"); EXPECT_EQ((two_pow_128_minus_1 >> 64), u64max); const auto two_pow_65_minus_1 = *Bn("36893488147419103231"); EXPECT_EQ((two_pow_65_minus_1 >> 63), Bignum(3)); Bignum b(20); b >>= 2; EXPECT_EQ(b, Bignum(5)); // Shifting zero or by zero amount. EXPECT_EQ((Bignum(0) >> 100), Bignum(0)); EXPECT_EQ((Bignum(123) >> 0), Bignum(123)); // Shifting to zero. EXPECT_EQ((Bignum(100) >> 100), Bignum(0)); } TEST(BignumTest, Multiplication) { // Zero EXPECT_EQ(Bignum(123) * Bignum(0), Bignum(0)); EXPECT_EQ(Bignum(0) * Bignum(456), Bignum(0)); // Identity EXPECT_EQ(Bignum(123) * Bignum(1), Bignum(123)); EXPECT_EQ(Bignum(1) * Bignum(456), Bignum(456)); EXPECT_EQ(Bignum(-123) * Bignum(1), Bignum(-123)); // Signs EXPECT_EQ(Bignum(10) * Bignum(20), Bignum(200)); EXPECT_EQ(Bignum(-10) * Bignum(20), Bignum(-200)); EXPECT_EQ(Bignum(10) * Bignum(-20), Bignum(-200)); EXPECT_EQ(Bignum(-10) * Bignum(-20), Bignum(200)); // Simple carry const auto bn_u32max = Bignum(kU32max); EXPECT_EQ(bn_u32max * Bignum(2), *Bn("8589934590")); // 1x1 bigit fast path const auto bn_u64max = Bignum(kU64max); EXPECT_EQ(Bignum(2) * bn_u64max, *Bn("36893488147419103230")); // 1xN bigit multiplication const auto two_pow_128_minus_1 = *Bn("340282366920938463463374607431768211455"); const auto res_1xN = *Bn("680564733841876926926749214863536422910"); EXPECT_EQ(two_pow_128_minus_1 * Bignum(2), res_1xN); // Check that aliasing doesn't cause problems. Bignum a(100); a *= a; EXPECT_EQ(a, Bignum(10000)); Bignum b = *Bn("10000000000000000000"); // > 64 bits b *= b; EXPECT_EQ(b, *Bn("100000000000000000000000000000000000000")); // Karatsuba threshold test // (2^128 - 1) * (2^128 - 1) = 2^256 - 2*2^128 + 1 // This should trigger karatsuba if the threshold is low enough. EXPECT_EQ(two_pow_128_minus_1 * two_pow_128_minus_1, *Bn("115792089237316195423570985008687907852589419931798687112530" "834793049593217025")); // Karatsuba with uneven operands EXPECT_EQ(two_pow_128_minus_1 * bn_u64max, *Bn("6277101735386680763495507056286727952620534092958556749825")); } TEST(BignumTest, CountrZero) { EXPECT_EQ(countr_zero(Bignum(0)), 0); EXPECT_EQ(countr_zero(Bignum(1)), 0); EXPECT_EQ(countr_zero(Bignum(7)), 0); EXPECT_EQ(countr_zero(Bignum(-7)), 0); EXPECT_EQ(countr_zero(Bignum(2)), 1); EXPECT_EQ(countr_zero(Bignum(8)), 3); EXPECT_EQ(countr_zero(Bignum(10)), 1); // 0b1010 EXPECT_EQ(countr_zero(Bignum(12)), 2); // 0b1100 auto two_pow_64 = Bignum(1) << 64; EXPECT_EQ(countr_zero(two_pow_64), 64); auto large_shifted = Bignum(6) << 100; // 0b110 << 100 EXPECT_EQ(countr_zero(large_shifted), 101); auto neg_large_shifted = Bignum(-5) << 200; EXPECT_EQ(countr_zero(neg_large_shifted), 200); } TEST(BignumTest, is_bit_set) { EXPECT_FALSE(Bignum(0).is_bit_set(0)); EXPECT_FALSE(Bignum(0).is_bit_set(100)); // 5 = 0b101 Bignum five(5); EXPECT_TRUE(five.is_bit_set(0)); EXPECT_FALSE(five.is_bit_set(1)); EXPECT_TRUE(five.is_bit_set(2)); EXPECT_FALSE(five.is_bit_set(3)); // Negative numbers should test the magnitude. Bignum neg_five(-5); EXPECT_TRUE(neg_five.is_bit_set(0)); EXPECT_FALSE(neg_five.is_bit_set(1)); EXPECT_TRUE(neg_five.is_bit_set(2)); // Test edges of and across bigits. Bignum high_is_bit_set_63 = Bignum(1) << 63; EXPECT_FALSE(high_is_bit_set_63.is_bit_set(62)); EXPECT_TRUE(high_is_bit_set_63.is_bit_set(63)); EXPECT_FALSE(high_is_bit_set_63.is_bit_set(64)); Bignum cross_bigit = (Bignum(1) << 100) + Bignum(1); EXPECT_TRUE(cross_bigit.is_bit_set(0)); EXPECT_TRUE(cross_bigit.is_bit_set(100)); EXPECT_FALSE(cross_bigit.is_bit_set(50)); EXPECT_FALSE(cross_bigit.is_bit_set(1000)); } TEST(BignumTest, Pow) { // Edge cases EXPECT_EQ(Bignum(0).Pow(0), Bignum(1)); EXPECT_EQ(Bignum(123).Pow(0), Bignum(1)); EXPECT_EQ(Bignum(0).Pow(123), Bignum(0)); EXPECT_EQ(Bignum(1).Pow(12345), Bignum(1)); // Negative base EXPECT_EQ(Bignum(-1).Pow(2), Bignum(1)); EXPECT_EQ(Bignum(-1).Pow(3), Bignum(-1)); EXPECT_EQ(Bignum(-2).Pow(2), Bignum(4)); EXPECT_EQ(Bignum(-2).Pow(3), Bignum(-8)); // Basic powers EXPECT_EQ(Bignum(2).Pow(10), Bignum(1024)); EXPECT_EQ(Bignum(3).Pow(5), Bignum(243)); EXPECT_EQ(Bignum(10).Pow(18), *Bn("1000000000000000000")); // Large exponent Bignum two_pow_100 = Bignum(1) << 100; EXPECT_EQ(Bignum(2).Pow(100), two_pow_100); // Large base Bignum ten_pow_19 = *Bn("10000000000000000000"); Bignum ten_pow_38 = *Bn("100000000000000000000000000000000000000"); EXPECT_EQ(ten_pow_19.Pow(2), ten_pow_38); } TEST(BignumTest, SetZero) { Bignum a(123); a.set_zero(); EXPECT_TRUE(a.is_zero()); Bignum b(-456); b.set_zero(); EXPECT_EQ(b, Bignum(0)); } TEST(BignumTest, SetNegativeSetPositive) { Bignum a(42); a.set_negative(); EXPECT_TRUE(a.is_negative()); EXPECT_EQ(a, Bignum(-42)); a.set_negative(false); EXPECT_FALSE(a.is_negative()); EXPECT_EQ(a, Bignum(42)); // set_negative() has no effect on zero. Bignum b(0); b.set_negative(); EXPECT_FALSE(b.is_negative()); EXPECT_EQ(b, Bignum(0)); } TEST(BignumTest, Comparisons) { EXPECT_EQ(*Bn("123"), Bignum(123)); EXPECT_EQ(*Bn("-123"), Bignum(-123)); EXPECT_NE(*Bn("123"), Bignum(-123)); EXPECT_EQ(Bignum(0), Bignum(0)); EXPECT_NE(Bignum(0), Bignum(1)); // Positive vs Positive EXPECT_LT(Bignum(100), Bignum(200)); EXPECT_GT(Bignum(200), Bignum(100)); EXPECT_LE(Bignum(100), Bignum(200)); EXPECT_GE(Bignum(200), Bignum(100)); // Negative vs Negative EXPECT_LT(Bignum(-200), Bignum(-100)); EXPECT_GT(Bignum(-100), Bignum(-200)); EXPECT_GE(Bignum(-100), Bignum(-200)); EXPECT_LE(Bignum(-200), Bignum(-100)); // Positive vs Negative EXPECT_LT(Bignum(-10), Bignum(10)); EXPECT_GT(Bignum(10), Bignum(-10)); // Zero EXPECT_LT(Bignum(-1), Bignum(0)); EXPECT_LT(Bignum(0), Bignum(1)); EXPECT_GT(Bignum(0), Bignum(-1)); EXPECT_GT(Bignum(1), Bignum(0)); // Multi-bigit const auto two_pow_64 = *Bn("18446744073709551616"); EXPECT_LT(Bignum(0), two_pow_64); EXPECT_GT(two_pow_64, Bignum(0)); EXPECT_LT(Bignum(-1), two_pow_64); EXPECT_GT(two_pow_64, Bignum(-1)); EXPECT_LE(Bignum(100), Bignum(200)); EXPECT_LE(Bignum(100), Bignum(100)); EXPECT_LE(Bignum(-200), Bignum(-100)); EXPECT_LE(Bignum(-100), Bignum(-100)); EXPECT_GT(Bignum(200), Bignum(100)); EXPECT_GE(Bignum(200), Bignum(100)); EXPECT_GE(Bignum(100), Bignum(100)); EXPECT_GE(Bignum(-100), Bignum(-200)); EXPECT_GE(Bignum(-100), Bignum(-100)); EXPECT_LT(Bignum(100), Bignum(200)); EXPECT_LE(Bignum(0), Bignum(0)); EXPECT_GE(Bignum(0), Bignum(0)); } // RAII wrapper for OpenSSL BIGNUM class OpenSSLBignum { public: OpenSSLBignum() : bn_(BN_new()) {} // Construct from a decimal number in a string. // // We take decimal as a string so that it's explicitly zero-terminated. explicit OpenSSLBignum(const std::string& decimal) : bn_(BN_new()) { BN_dec2bn(&bn_, decimal.data()); } explicit OpenSSLBignum(uint64_t value) : bn_(BN_new()) { BN_set_word(bn_, value); } ~OpenSSLBignum() { BN_free(bn_); } OpenSSLBignum(OpenSSLBignum&& other) noexcept : bn_(other.bn_) { other.bn_ = nullptr; } OpenSSLBignum& operator=(OpenSSLBignum&& other) noexcept { if (this != &other) { BN_free(bn_); bn_ = other.bn_; other.bn_ = nullptr; } return *this; } OpenSSLBignum(const OpenSSLBignum& other) : bn_(BN_dup(other.bn_)) {} OpenSSLBignum& operator=(const OpenSSLBignum& other) { if (this != &other) { BN_copy(bn_, other.bn_); } return *this; } BIGNUM* get() const { return bn_; } private: BIGNUM* bn_; }; // Power of two for fast modulo. const int kRandomBignumCount = 128; static std::vector GenerateRandomNumberStrings( absl::BitGenRef bitgen, int bits) { std::vector numbers; numbers.reserve(kRandomBignumCount); for (int i = 0; i < kRandomBignumCount; ++i) { std::string num; // Generate approximately `bits` worth of decimal digits int decimal_digits = (bits * 3) / 10; // log10(2^bits) ≈ bits * 0.301 // First digit can't be zero absl::StrAppend(&num, absl::StrFormat("%d", absl::Uniform(bitgen, 1, 9))); for (int j = 1; j < decimal_digits; ++j) { num += absl::Uniform(bitgen, '0', '9'); } numbers.push_back(num); } return numbers; } // Basic correctness test to ensure OpenSSL integration is working TEST(BignumTest, OpenSSLIntegration) { OpenSSLBignum a(123); OpenSSLBignum b(456); OpenSSLBignum result; BN_add(result.get(), a.get(), b.get()); char* str = BN_bn2dec(result.get()); EXPECT_STREQ(str, "579"); OPENSSL_free(str); } TEST(BignumTest, ResultsMatch) { // Test that and OpenSSL produce the same results const Bignum w_a(12345); const Bignum w_b(67890); Bignum w_result = w_a + w_b; const OpenSSLBignum ssl_a(12345); const OpenSSLBignum ssl_b(67890); OpenSSLBignum ssl_result; BN_add(ssl_result.get(), ssl_a.get(), ssl_b.get()); char* ssl_str = BN_bn2dec(ssl_result.get()); std::string w_str = absl::StrFormat("%v", w_result); EXPECT_EQ(w_str, std::string(ssl_str)); OPENSSL_free(ssl_str); } // Different number sizes for benchmarking. enum class NumberSizeClass : uint32_t { kSmall = 64, kMedium = 256, kLarge = 1024, kHuge = 4096, kMega = 18000 }; std::vector RandomNumberStrings(absl::BitGenRef bitgen, NumberSizeClass size_class) { return GenerateRandomNumberStrings(bitgen, static_cast(size_class)); } class VsOpenSSLTest : public TestWithParam> { protected: // Returns a vector of pairs of numbers (as decimal strings) based on the // parameters that the test suite was created with. // // E.g. If the test suite was instantiate with (kSmall, kHuge) as the number // classes, then this will return a small value on the left and a huge value // on the right. (kHuge, kSmall) would return the opposite. std::vector> Numbers( absl::BitGenRef bitgen) { auto numbers0 = RandomNumberStrings(bitgen, GetParam().first); auto numbers1 = RandomNumberStrings(bitgen, GetParam().second); ABSL_CHECK_EQ(numbers0.size(), numbers1.size()); std::vector> numbers; numbers.reserve(numbers0.size()); for (size_t i = 0; i < numbers0.size(); ++i) { numbers.emplace_back(numbers0[i], numbers1[i]); } return numbers; } }; TEST_P(VsOpenSSLTest, MultiplyCorrect) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "MULTIPLY_CORRECT", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); // Test that multiplication produces the same results as OpenSSL. BN_CTX* ctx = BN_CTX_new(); for (const auto& [a, b] : Numbers(bitgen)) { const Bignum bn_a = *Bignum::FromString(a); const Bignum bn_b = *Bignum::FromString(b); const Bignum bn_result = bn_a * bn_b; const OpenSSLBignum ssl_a(a); const OpenSSLBignum ssl_b(b); OpenSSLBignum ssl_result; BN_mul(ssl_result.get(), ssl_a.get(), ssl_b.get(), ctx); // Compare string representations char* ssl_str = BN_bn2dec(ssl_result.get()); std::string bn_str = absl::StrFormat("%v", bn_result); EXPECT_EQ(bn_str, std::string(ssl_str)) << "Mismatch for multiplication" << "\nBignum result: " << bn_str.substr(0, 100) << "..." << "\nOpenSSL result: " << std::string(ssl_str).substr(0, 100) << "..."; OPENSSL_free(ssl_str); } BN_CTX_free(ctx); } TEST_P(VsOpenSSLTest, AdditionCorrect) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "ADDITION_CORRECT", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); // Test that addition produces correct results by comparing to OpenSSL. for (const auto& [a, b] : Numbers(bitgen)) { const Bignum bn_a = *Bignum::FromString(a); const Bignum bn_b = *Bignum::FromString(b); const Bignum bn_result = bn_a + bn_b; const OpenSSLBignum ssl_a(a); const OpenSSLBignum ssl_b(b); OpenSSLBignum ssl_result; BN_add(ssl_result.get(), ssl_a.get(), ssl_b.get()); // Compare string representations char* ssl_str = BN_bn2dec(ssl_result.get()); std::string bn_str = absl::StrFormat("%v", bn_result); EXPECT_EQ(bn_str, std::string(ssl_str)) << "Mismatch for addition" << "\nBignum result: " << bn_str.substr(0, 100) << "..." << "\nOpenSSL result: " << std::string(ssl_str).substr(0, 100) << "..."; OPENSSL_free(ssl_str); } } TEST_P(VsOpenSSLTest, SubtractionCorrect) { absl::BitGen bitgen(S2Testing::MakeTaggedSeedSeq( "SUBTRACTION_CORRECT", absl::LogInfoStreamer(__FILE__, __LINE__).stream())); // Test that subtraction produces correct results by comparing to // OpenSSL. for (const auto& [a, b] : Numbers(bitgen)) { const Bignum bn_a = *Bignum::FromString(a); const Bignum bn_b = *Bignum::FromString(b); const Bignum bn_result = bn_a - bn_b; const OpenSSLBignum ssl_a(a); const OpenSSLBignum ssl_b(b); OpenSSLBignum ssl_result; BN_sub(ssl_result.get(), ssl_a.get(), ssl_b.get()); // Compare string representations char* ssl_str = BN_bn2dec(ssl_result.get()); std::string bn_str = absl::StrFormat("%v", bn_result); EXPECT_EQ(bn_str, std::string(ssl_str)) << "Mismatch for addition" << "\nBignum result: " << bn_str.substr(0, 100) << "..." << "\nOpenSSL result: " << std::string(ssl_str).substr(0, 100) << "..."; OPENSSL_free(ssl_str); } } // clang-format off INSTANTIATE_TEST_SUITE_P( VsOpenSSL, VsOpenSSLTest, ::testing::Values( std::make_pair(NumberSizeClass::kSmall, NumberSizeClass::kSmall), std::make_pair(NumberSizeClass::kSmall, NumberSizeClass::kHuge), std::make_pair(NumberSizeClass::kHuge, NumberSizeClass::kSmall), std::make_pair(NumberSizeClass::kMedium, NumberSizeClass::kMedium), std::make_pair(NumberSizeClass::kLarge, NumberSizeClass::kLarge), std::make_pair(NumberSizeClass::kHuge, NumberSizeClass::kHuge), std::make_pair(NumberSizeClass::kMega, NumberSizeClass::kMega))); // clang-format on // TODO: Enable once benchmark is integrated. #if 0 template void BignumBinaryOpBenchmark(benchmark::State& state, const std::vector& number_strings, BinaryOp op) { std::vector numbers; for (const auto& str : number_strings) { numbers.push_back(*Bignum::FromString(str)); } Bignum result; size_t idx = 0; for (auto _ : state) { const Bignum& a = numbers[(idx + 0) % kRandomBignumCount]; const Bignum& b = numbers[(idx + 1) % kRandomBignumCount]; result = op(a, b); benchmark::DoNotOptimize(result); ++idx; } } void BignumPowBenchmark(benchmark::State& state, const std::vector& number_strings, int exponent) { std::vector numbers; for (const auto& str : number_strings) { numbers.push_back(*Bignum::FromString(str)); } Bignum result; size_t idx = 0; for (auto _ : state) { const Bignum& base = numbers[(idx + 0) % kRandomBignumCount]; result = base.Pow(exponent); benchmark::DoNotOptimize(result); ++idx; } } template void OpenSSLBinaryOpBenchmark(benchmark::State& state, const std::vector& number_strings, BinaryOp op) { std::vector numbers; for (const auto& str : number_strings) { numbers.emplace_back(str); } size_t idx = 0; for (auto _ : state) { OpenSSLBignum result; const OpenSSLBignum& a = numbers[(idx + 0) % kRandomBignumCount]; const OpenSSLBignum& b = numbers[(idx + 1) % kRandomBignumCount]; op(result.get(), a.get(), b.get()); benchmark::DoNotOptimize(result.get()); ++idx; } } template void OpenSSLMulOpBenchmark(benchmark::State& state, const std::vector& number_strings, MulOp op) { std::vector numbers; for (const auto& str : number_strings) { numbers.emplace_back(str); } BN_CTX* ctx = BN_CTX_new(); size_t idx = 0; for (auto _ : state) { OpenSSLBignum result; const OpenSSLBignum& a = numbers[(idx + 0) % kRandomBignumCount]; const OpenSSLBignum& b = numbers[(idx + 1) % kRandomBignumCount]; op(result.get(), a.get(), b.get(), ctx); benchmark::DoNotOptimize(result.get()); ++idx; } BN_CTX_free(ctx); } void OpenSSLPowBenchmark(benchmark::State& state, const std::vector& number_strings, int exponent) { std::vector numbers; for (const auto& str : number_strings) { numbers.emplace_back(str); } const OpenSSLBignum exp(exponent); BN_CTX* ctx = BN_CTX_new(); size_t idx = 0; for (auto _ : state) { OpenSSLBignum result; const OpenSSLBignum& base = numbers[(idx + 0) % kRandomBignumCount]; BN_exp(result.get(), base.get(), exp.get(), ctx); benchmark::DoNotOptimize(result.get()); ++idx; } BN_CTX_free(ctx); } std::vector SmallNumbers(absl::BitGenRef bitgen) { return RandomNumberStrings(bitgen, NumberSizeClass::kSmall); } std::vector MediumNumbers(absl::BitGenRef bitgen) { return RandomNumberStrings(bitgen, NumberSizeClass::kMedium); } std::vector LargeNumbers(absl::BitGenRef bitgen) { return RandomNumberStrings(bitgen, NumberSizeClass::kLarge); } std::vector HugeNumbers(absl::BitGenRef bitgen) { return RandomNumberStrings(bitgen, NumberSizeClass::kHuge); } std::vector MegaNumbers(absl::BitGenRef bitgen) { return RandomNumberStrings(bitgen, NumberSizeClass::kMega); } void BM_Bignum_AddSmall(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, SmallNumbers(bitgen), std::plus{}); } BENCHMARK(BM_Bignum_AddSmall); void BM_Bignum_AddMedium(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, MediumNumbers(bitgen), std::plus{}); } BENCHMARK(BM_Bignum_AddMedium); void BM_Bignum_AddLarge(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, LargeNumbers(bitgen), std::plus{}); } BENCHMARK(BM_Bignum_AddLarge); void BM_Bignum_AddHuge(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, HugeNumbers(bitgen), std::plus{}); } BENCHMARK(BM_Bignum_AddHuge); void BM_Bignum_AddMega(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, MegaNumbers(bitgen), std::plus{}); } BENCHMARK(BM_Bignum_AddMega); void BM_OpenSSL_AddSmall(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLBinaryOpBenchmark(state, SmallNumbers(bitgen), BN_add); } BENCHMARK(BM_OpenSSL_AddSmall); void BM_OpenSSL_AddMedium(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLBinaryOpBenchmark(state, MediumNumbers(bitgen), BN_add); } BENCHMARK(BM_OpenSSL_AddMedium); void BM_OpenSSL_AddLarge(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLBinaryOpBenchmark(state, LargeNumbers(bitgen), BN_add); } BENCHMARK(BM_OpenSSL_AddLarge); void BM_OpenSSL_AddHuge(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLBinaryOpBenchmark(state, HugeNumbers(bitgen), BN_add); } BENCHMARK(BM_OpenSSL_AddHuge); void BM_OpenSSL_AddMega(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLBinaryOpBenchmark(state, MegaNumbers(bitgen), BN_add); } BENCHMARK(BM_OpenSSL_AddMega); void BM_Bignum_MulSmall(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, SmallNumbers(bitgen), std::multiplies{}); } BENCHMARK(BM_Bignum_MulSmall); void BM_Bignum_MulMedium(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, MediumNumbers(bitgen), std::multiplies{}); } BENCHMARK(BM_Bignum_MulMedium); void BM_Bignum_MulLarge(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, LargeNumbers(bitgen), std::multiplies{}); } BENCHMARK(BM_Bignum_MulLarge); void BM_Bignum_MulHuge(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, HugeNumbers(bitgen), std::multiplies{}); } BENCHMARK(BM_Bignum_MulHuge); void BM_Bignum_MulMega(benchmark::State& state) { std::mt19937_64 bitgen; BignumBinaryOpBenchmark(state, MegaNumbers(bitgen), std::multiplies{}); } BENCHMARK(BM_Bignum_MulMega); void BM_OpenSSL_MulSmall(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLMulOpBenchmark(state, SmallNumbers(bitgen), BN_mul); } BENCHMARK(BM_OpenSSL_MulSmall); void BM_OpenSSL_MulMedium(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLMulOpBenchmark(state, MediumNumbers(bitgen), BN_mul); } BENCHMARK(BM_OpenSSL_MulMedium); void BM_OpenSSL_MulLarge(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLMulOpBenchmark(state, LargeNumbers(bitgen), BN_mul); } BENCHMARK(BM_OpenSSL_MulLarge); void BM_OpenSSL_MulHuge(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLMulOpBenchmark(state, HugeNumbers(bitgen), BN_mul); } BENCHMARK(BM_OpenSSL_MulHuge); void BM_OpenSSL_MulMega(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLMulOpBenchmark(state, MegaNumbers(bitgen), BN_mul); } BENCHMARK(BM_OpenSSL_MulMega); void BM_Bignum_PowSmall(benchmark::State& state) { std::mt19937_64 bitgen; BignumPowBenchmark(state, SmallNumbers(bitgen), 20); } BENCHMARK(BM_Bignum_PowSmall); void BM_Bignum_PowMedium(benchmark::State& state) { std::mt19937_64 bitgen; BignumPowBenchmark(state, MediumNumbers(bitgen), 10); } BENCHMARK(BM_Bignum_PowMedium); void BM_OpenSSL_PowSmall(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLPowBenchmark(state, SmallNumbers(bitgen), 20); } BENCHMARK(BM_OpenSSL_PowSmall); void BM_OpenSSL_PowMedium(benchmark::State& state) { std::mt19937_64 bitgen; OpenSSLPowBenchmark(state, MediumNumbers(bitgen), 10); } BENCHMARK(BM_OpenSSL_PowMedium); #endif } // namespace exactfloat_internal src/s2/util/math/exactfloat/exactfloat.cc000066400000000000000000000546341524103652300207070ustar00rootroot00000000000000// Copyright 2009 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/util/math/exactfloat/exactfloat.h" #include #include #include #include #include #include #include #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/strings/str_cat.h" #include "absl/strings/str_format.h" namespace exactfloat { using std::max; // To simplify the overflow/underflow logic, we limit the exponent and // precision range so that (2 * bn_exp_) does not overflow an "int". We take // advantage of this, for example, by only checking for overflow/underflow // *after* multiplying two numbers. static_assert(ExactFloat::kMaxExp <= INT_MAX / 2 && ExactFloat::kMinExp - ExactFloat::kMaxPrec >= INT_MIN / 2, "exactfloat exponent might overflow"); ExactFloat::ExactFloat(double v) { sign_ = std::signbit(v) ? -1 : 1; if (std::isnan(v)) { set_nan(); } else if (std::isinf(v)) { set_inf(sign_); } else { // The following code is much simpler than messing about with bit masks, // has the advantage of handling denormalized numbers and zero correctly, // and is actually quite efficient (at least compared to the rest of this // code). "f" is a fraction in the range [0.5, 1), so if we shift it left // by the number of mantissa bits in a double (53, including the leading // "1") then the result is always an integer. int exp; double f = std::frexp(std::fabs(v), &exp); uint64_t m = static_cast(std::ldexp(f, kDoubleMantissaBits)); bn_ = Bignum(m); bn_exp_ = exp - kDoubleMantissaBits; Canonicalize(); } } // Calculates abs(v) without UB. SafeAbs(INT_MIN) == INT_MIN. // Generates the same code as std::abs(). // https://godbolt.org/z/eT6KW1zGb unsigned SafeAbs(int v) { return v < 0 ? -static_cast(v) : v; } ExactFloat::ExactFloat(int v) { sign_ = (v >= 0) ? 1 : -1; bn_exp_ = 0; bn_ = Bignum(SafeAbs(v)); Canonicalize(); } ExactFloat ExactFloat::SignedZero(int sign) { ExactFloat r; r.set_zero(sign); return r; } ExactFloat ExactFloat::Infinity(int sign) { ExactFloat r; r.set_inf(sign); return r; } ExactFloat ExactFloat::NaN() { ExactFloat r; r.set_nan(); return r; } int ExactFloat::prec() const { return bit_width(bn_); } int ExactFloat::exp() const { ABSL_DCHECK(isnormal(*this)); return bn_exp_ + bit_width(bn_); } void ExactFloat::set_zero(int sign) { sign_ = sign; bn_exp_ = kExpZero; bn_.set_zero(); } void ExactFloat::set_inf(int sign) { sign_ = sign; bn_exp_ = kExpInfinity; bn_.set_zero(); } void ExactFloat::set_nan() { sign_ = 1; bn_exp_ = kExpNaN; bn_.set_zero(); } int fpclassify(ExactFloat const& x) { switch (x.bn_exp_) { case ExactFloat::kExpNaN: return FP_NAN; case ExactFloat::kExpInfinity: return FP_INFINITE; case ExactFloat::kExpZero: return FP_ZERO; // There are no subnormal `ExactFloat`s. default: return FP_NORMAL; } } ExactFloat::operator double() const { // If the mantissa has too many bits, we need to round it. if (prec() <= kDoubleMantissaBits) { return ToDoubleHelper(); } else { ExactFloat r = RoundToMaxPrec(kDoubleMantissaBits, kRoundTiesToEven); return r.ToDoubleHelper(); } } double ExactFloat::ToDoubleHelper() const { ABSL_DCHECK_LE(bit_width(bn_), kDoubleMantissaBits); if (!isnormal(*this)) { if (is_zero()) return std::copysign(0, sign_); if (isinf(*this)) { return std::copysign(std::numeric_limits::infinity(), sign_); } return std::copysign(std::numeric_limits::quiet_NaN(), sign_); } const double d_mantissa = static_cast(bn_.Cast()); // We rely on ldexp() to handle overflow and underflow. (It will return a // signed zero or infinity if the result is too small or too large.) return sign_ * std::ldexp(d_mantissa, bn_exp_); } ExactFloat ExactFloat::RoundToMaxPrec(int max_prec, RoundingMode mode) const { // The "kRoundTiesToEven" mode requires at least 2 bits of precision // (otherwise both adjacent representable values may be odd). ABSL_DCHECK_GE(max_prec, 2); ABSL_DCHECK_LE(max_prec, kMaxPrec); // The following test also catches zero, infinity, and NaN. int shift = prec() - max_prec; if (shift <= 0) return *this; // Round by removing the appropriate number of bits from the mantissa. Note // that if the value is rounded up to a power of 2, the high-order bit // position may increase, but in that case Canonicalize() will remove at // least one zero bit and so the output will still have prec() <= max_prec. return RoundToPowerOf2(bn_exp_ + shift, mode); } ExactFloat ExactFloat::RoundToPowerOf2(int bit_exp, RoundingMode mode) const { ABSL_DCHECK_GE(bit_exp, kMinExp - kMaxPrec); ABSL_DCHECK_LE(bit_exp, kMaxExp); // If the exponent is already large enough, or the value is zero, infinity, // or NaN, then there is nothing to do. int shift = bit_exp - bn_exp_; if (shift <= 0) return *this; ABSL_DCHECK(isnormal(*this)); // Convert rounding up/down to toward/away from zero, so that we don't need // to consider the sign of the number from this point onward. if (mode == kRoundTowardPositive) { mode = (sign_ > 0) ? kRoundAwayFromZero : kRoundTowardZero; } else if (mode == kRoundTowardNegative) { mode = (sign_ > 0) ? kRoundTowardZero : kRoundAwayFromZero; } // Rounding consists of right-shifting the mantissa by "shift", and then // possibly incrementing the result (depending on the rounding mode, the // bits that were discarded, and sometimes the lowest kept bit). The // following code figures out whether we need to increment. ExactFloat r; bool increment = false; if (mode == kRoundTowardZero) { // Never increment. } else if (mode == kRoundTiesAwayFromZero) { // Increment if the highest discarded bit is 1. if (bn_.is_bit_set(shift - 1)) increment = true; } else if (mode == kRoundAwayFromZero) { // Increment unless all discarded bits are zero. if (countr_zero(bn_) < shift) increment = true; } else { ABSL_DCHECK_EQ(mode, kRoundTiesToEven); // Let "w/xyz" denote a mantissa where "w" is the lowest kept bit and // "xyz" are the discarded bits. Then using regexp notation: // ./0.* -> Don't increment (fraction < 1/2) // 0/10* -> Don't increment (fraction = 1/2, kept part even) // 1/10* -> Increment (fraction = 1/2, kept part odd) // ./1.*1.* -> Increment (fraction > 1/2) if (bn_.is_bit_set(shift - 1) && ((bn_.is_bit_set(shift) || countr_zero(bn_) < shift - 1))) { increment = true; } } r.bn_exp_ = bn_exp_ + shift; r.bn_ = bn_ >> shift; if (increment) { r.bn_ += Bignum(1); } r.sign_ = sign_; r.Canonicalize(); return r; } int ExactFloat::NumSignificantDigitsForPrec(int prec) { // The simplest bound is // // d <= 1 + ceil(prec * log10(2)) // // The following bound is tighter by 0.5 digits on average, but requires // the exponent to be known as well: // // d <= ceil(exp * log10(2)) - floor((exp - prec) * log10(2)) // // Since either of these bounds can be too large by 0, 1, or 2 digits, we // stick with the simpler first bound. return static_cast(1 + std::ceil(prec * (M_LN2 / M_LN10))); } // Numbers are always formatted with at least this many significant digits. // This prevents small integers from being formatted in exponential notation // (e.g. 1024 formatted as 1e+03), and also avoids the confusion of having // supposedly "high precision" numbers formatted with just 1 or 2 digits // (e.g. 1/512 == 0.001953125 formatted as 0.002). static const int kMinSignificantDigits = 10; std::string ExactFloat::ToString() const { int max_digits = max(kMinSignificantDigits, NumSignificantDigitsForPrec(prec())); return ToStringWithMaxDigits(max_digits); } std::string ExactFloat::ToStringWithMaxDigits(int max_digits) const { ABSL_DCHECK_GT(max_digits, 0); if (!isnormal(*this)) { if (isnan(*this)) return "nan"; if (is_zero()) return (sign_ < 0) ? "-0" : "0"; return (sign_ < 0) ? "-inf" : "inf"; } std::string digits; int exp10 = GetDecimalDigits(max_digits, &digits); std::string str; if (sign_ < 0) str.push_back('-'); // We use the standard '%g' formatting rules. If the exponent is less than // -4 or greater than or equal to the requested precision (i.e., max_digits) // then we use exponential notation. // // But since "exp10" is the base-10 exponent corresponding to a mantissa in // the range [0.1, 1), whereas the '%g' rules assume a mantissa in the range // [1.0, 10), we need to adjust these parameters by 1. if (exp10 <= -4 || exp10 > max_digits) { // Use exponential format. str.push_back(digits[0]); if (digits.size() > 1) { str.push_back('.'); str.append(digits.begin() + 1, digits.end()); } absl::StrAppendFormat(&str, "e%+02d", exp10 - 1); } else { // Use fixed format. We split this into two cases depending on whether // the integer portion is non-zero or not. if (exp10 > 0) { if (static_cast(exp10) >= digits.size()) { absl::StrAppend(&str, digits); for (int i = exp10 - digits.size(); i > 0; --i) { str.push_back('0'); } } else { str.append(digits.begin(), digits.begin() + exp10); str.push_back('.'); str.append(digits.begin() + exp10, digits.end()); } } else { absl::StrAppend(&str, "0."); for (int i = exp10; i < 0; ++i) { str.push_back('0'); } absl::StrAppend(&str, digits); } } return str; } // Increment an unsigned integer represented as a string of ASCII digits. static void IncrementDecimalDigits(std::string* digits) { std::string::iterator pos = digits->end(); while (--pos >= digits->begin()) { if (*pos < '9') { ++*pos; return; } *pos = '0'; } digits->insert(0, "1"); } int ExactFloat::GetDecimalDigits(int max_digits, std::string* digits) const { ABSL_DCHECK(isnormal(*this)); // Convert the value to the form (bn * (10 ** bn_exp10)) where "bn" is a // positive integer. Bignum bn; int bn_exp10; if (bn_exp_ >= 0) { // The easy case: bn = bn_ * (2 ** bn_exp_)), bn_exp10 = 0. bn = bn_ << bn_exp_; bn_exp10 = 0; } else { // Set bn = bn_ * (5 ** -bn_exp_) and bn_exp10 = bn_exp_. This is // equivalent to the original value of (bn_ * (2 ** bn_exp_)). bn = bn_ * Bignum(5).Pow(-bn_exp_); bn_exp10 = bn_exp_; } // Now convert "bn" to a decimal string using our Bignum's string conversion. std::string all_digits = absl::StrFormat("%v", bn); ABSL_DCHECK(!all_digits.empty()); // Check whether we have too many digits and round if necessary. int num_digits = all_digits.length(); if (num_digits <= max_digits) { *digits = all_digits; } else { digits->assign(all_digits, 0, max_digits); // Standard "printf" formatting rounds ties to an even number. This means // that we round up (away from zero) if highest discarded digit is '5' or // more, unless all other discarded digits are zero in which case we round // up only if the lowest kept digit is odd. if (all_digits[max_digits] >= '5' && ((all_digits[max_digits - 1] & 1) == 1 || all_digits.find_first_not_of('0', max_digits + 1) != std::string::npos)) { // This can increase the number of digits by 1, but in that case at // least one trailing zero will be stripped off below. IncrementDecimalDigits(digits); } // Adjust the base-10 exponent to reflect the digits we have removed. bn_exp10 += num_digits - max_digits; } // Now strip any trailing zeros. ABSL_DCHECK_NE((*digits)[0], '0'); std::string::size_type pos = digits->find_last_not_of('0') + 1; bn_exp10 += digits->size() - pos; digits->erase(pos); ABSL_DCHECK_LE(static_cast(digits->size()), max_digits); // Finally, we adjust the base-10 exponent so that the mantissa is a // fraction in the range [0.1, 1) rather than an integer. return bn_exp10 + digits->size(); } std::string ExactFloat::ToUniqueString() const { return absl::StrFormat("%s<%d>", ToString(), prec()); } ExactFloat ExactFloat::operator-() const { return CopyWithSign(-sign_); } ExactFloat operator+(const ExactFloat& a, const ExactFloat& b) { return ExactFloat::SignedSum(a.sign_, &a, b.sign_, &b); } ExactFloat operator-(const ExactFloat& a, const ExactFloat& b) { return ExactFloat::SignedSum(a.sign_, &a, -b.sign_, &b); } ExactFloat ExactFloat::SignedSum(int a_sign, const ExactFloat* a, int b_sign, const ExactFloat* b) { if (!isnormal(*a) || !isnormal(*b)) { // Handle zero, infinity, and NaN according to IEEE 754-2008. if (isnan(*a)) return *a; if (isnan(*b)) return *b; if (isinf(*a)) { // Adding two infinities with opposite sign yields NaN. if (isinf(*b) && a_sign != b_sign) return NaN(); return Infinity(a_sign); } if (isinf(*b)) return Infinity(b_sign); if (a->is_zero()) { if (!b->is_zero()) return b->CopyWithSign(b_sign); // Adding two zeros with the same sign preserves the sign. if (a_sign == b_sign) return SignedZero(a_sign); // Adding two zeros of opposite sign produces +0. return SignedZero(+1); } ABSL_DCHECK(b->is_zero()); return a->CopyWithSign(a_sign); } // Swap the numbers if necessary so that "a" has the larger bn_exp_. if (a->bn_exp_ < b->bn_exp_) { using std::swap; swap(a_sign, b_sign); swap(a, b); } // Shift "a" if necessary so that both values have the same bn_exp_. ExactFloat r; r.bn_ = a->bn_; r.bn_ <<= (a->bn_exp_ - b->bn_exp_); r.bn_exp_ = b->bn_exp_; if (a_sign == b_sign) { r.bn_ += b->bn_; r.sign_ = a_sign; } else { r.bn_ -= b->bn_; if (r.bn_.is_zero()) { r.sign_ = +1; } else if (r.bn_.is_negative()) { // |b| was greater than |a|. r.sign_ = b_sign; r.bn_.set_negative(false); } else { // |a| was greater than |b| r.sign_ = a_sign; } } r.Canonicalize(); return r; } void ExactFloat::Canonicalize() { if (!isnormal(*this)) return; // Underflow/overflow occurs if exp() is not in [kMinExp, kMaxExp]. // We also convert a zero mantissa to signed zero. int my_exp = exp(); if (my_exp < kMinExp || bn_.is_zero()) { set_zero(sign_); } else if (my_exp > kMaxExp) { set_inf(sign_); } else if (bn_.is_even()) { // Remove any low-order zero bits from the mantissa. ABSL_DCHECK(!bn_.is_zero()); int shift = countr_zero(bn_); if (shift > 0) { bn_ >>= shift; bn_exp_ += shift; } } // If the mantissa has too many bits, we replace it by NaN to indicate // that an inexact calculation has occurred. if (prec() > kMaxPrec) { set_nan(); } } ExactFloat operator*(const ExactFloat& a, const ExactFloat& b) { int result_sign = a.sign_ * b.sign_; if (!isnormal(a) || !isnormal(b)) { // Handle zero, infinity, and NaN according to IEEE 754-2008. if (isnan(a)) return a; if (isnan(b)) return b; if (isinf(a)) { // Infinity times zero yields NaN. if (b.is_zero()) return ExactFloat::NaN(); return ExactFloat::Infinity(result_sign); } if (isinf(b)) { if (a.is_zero()) return ExactFloat::NaN(); return ExactFloat::Infinity(result_sign); } ABSL_DCHECK(a.is_zero() || b.is_zero()); return ExactFloat::SignedZero(result_sign); } ExactFloat r; r.sign_ = result_sign; r.bn_exp_ = a.bn_exp_ + b.bn_exp_; r.bn_ = a.bn_ * b.bn_; r.Canonicalize(); return r; } bool operator==(const ExactFloat& a, const ExactFloat& b) { // NaN is not equal to anything, not even itself. if (isnan(a) || isnan(b)) return false; // Since Canonicalize() strips low-order zero bits, all other cases // (including non-normal values) require bn_exp_ to be equal. if (a.bn_exp_ != b.bn_exp_) return false; // Positive and negative zero are equal. if (a.is_zero() && b.is_zero()) return true; // Otherwise, the signs and mantissas must match. Note that non-normal // values such as infinity have a mantissa of zero. return a.sign_ == b.sign_ && a.bn_ == b.bn_; } int ExactFloat::ScaleAndCompare(const ExactFloat& b) const { ABSL_DCHECK(isnormal(*this) && isnormal(b) && bn_exp_ >= b.bn_exp_); ExactFloat tmp = *this; tmp.bn_ <<= (bn_exp_ - b.bn_exp_); return tmp.bn_.Compare(b.bn_); } bool ExactFloat::UnsignedLess(const ExactFloat& b) const { // Handle the zero/infinity cases (NaN has already been done). if (isinf(*this) || b.is_zero()) return false; if (is_zero() || isinf(b)) return true; // If the high-order bit positions differ, we are done. int cmp = exp() - b.exp(); if (cmp != 0) return cmp < 0; // Otherwise shift one of the two values so that they both have the same // bn_exp_ and then compare the mantissas. return (bn_exp_ >= b.bn_exp_ ? ScaleAndCompare(b) < 0 : b.ScaleAndCompare(*this) > 0); } bool operator<(const ExactFloat& a, const ExactFloat& b) { // NaN is unordered compared to everything, including itself. if (isnan(a) || isnan(b)) return false; // Positive and negative zero are equal. if (a.is_zero() && b.is_zero()) return false; // Otherwise, anything negative is less than anything positive. if (a.sign_ != b.sign_) return a.sign_ < b.sign_; // Now we just compare absolute values. return (a.sign_ > 0) ? a.UnsignedLess(b) : b.UnsignedLess(a); } ExactFloat fabs(const ExactFloat& a) { return abs(a); } ExactFloat abs(const ExactFloat& a) { return a.CopyWithSign(+1); } ExactFloat fmax(const ExactFloat& a, const ExactFloat& b) { // If one argument is NaN, return the other argument. if (isnan(a)) return b; if (isnan(b)) return a; // Not required by IEEE 754, but we prefer +0 over -0. if (a.sign_ != b.sign_) { return (a.sign_ < b.sign_) ? b : a; } return (a < b) ? b : a; } ExactFloat fmin(const ExactFloat& a, const ExactFloat& b) { // If one argument is NaN, return the other argument. if (isnan(a)) return b; if (isnan(b)) return a; // Not required by IEEE 754, but we prefer -0 over +0. if (a.sign_ != b.sign_) { return (a.sign_ < b.sign_) ? a : b; } return (a < b) ? a : b; } ExactFloat fdim(const ExactFloat& a, const ExactFloat& b) { // This formulation has the correct behavior for NaNs. return (a <= b) ? 0 : (a - b); } ExactFloat ceil(const ExactFloat& a) { return a.RoundToPowerOf2(0, ExactFloat::kRoundTowardPositive); } ExactFloat floor(const ExactFloat& a) { return a.RoundToPowerOf2(0, ExactFloat::kRoundTowardNegative); } ExactFloat trunc(const ExactFloat& a) { return a.RoundToPowerOf2(0, ExactFloat::kRoundTowardZero); } ExactFloat round(const ExactFloat& a) { return a.RoundToPowerOf2(0, ExactFloat::kRoundTiesAwayFromZero); } ExactFloat rint(const ExactFloat& a) { return a.RoundToPowerOf2(0, ExactFloat::kRoundTiesToEven); } template T ExactFloat::ToInteger(RoundingMode mode) const { using std::numeric_limits; static_assert(sizeof(T) <= sizeof(uint64_t), "max 64 bits supported"); static_assert(numeric_limits::is_signed, "only signed types supported"); const int64_t kMinValue = numeric_limits::min(); const int64_t kMaxValue = numeric_limits::max(); ExactFloat r = RoundToPowerOf2(0, mode); if (isnan(r)) return kMaxValue; if (r.is_zero()) return 0; if (!isinf(r)) { // If the unsigned value has more than 63 bits it is always clamped. if (r.exp() < 64) { int64_t value = r.bn_.Cast() << r.bn_exp_; if (r.sign_ < 0) value = -value; return std::clamp(value, kMinValue, kMaxValue); } } return (r.sign_ < 0) ? kMinValue : kMaxValue; } // NOLINTBEGIN(runtime/int, google-runtime-int) long lrint(const ExactFloat& a) { return a.ToInteger(ExactFloat::kRoundTiesToEven); } long long llrint(const ExactFloat& a) { return a.ToInteger(ExactFloat::kRoundTiesToEven); } long lround(const ExactFloat& a) { return a.ToInteger(ExactFloat::kRoundTiesAwayFromZero); } long long llround(const ExactFloat& a) { return a.ToInteger(ExactFloat::kRoundTiesAwayFromZero); } // NOLINTEND(runtime/int, google-runtime-int) ExactFloat copysign(const ExactFloat& a, const ExactFloat& b) { return a.CopyWithSign(b.sign_); } ExactFloat frexp(const ExactFloat& a, int* exp) { if (!isnormal(a)) { // If a == 0, exp should be zero. If a.is_inf() or a.is_nan(), exp is not // defined but the glibc implementation returns zero. *exp = 0; return a; } *exp = a.exp(); return ldexp(a, -a.exp()); } ExactFloat ldexp(const ExactFloat& a, int exp) { if (!isnormal(a)) return a; // To prevent integer overflow, we first clamp "exp" so that // (kMinExp - 1) <= (a_exp + exp) <= (kMaxExp + 1). int a_exp = a.exp(); exp = std::clamp(exp, // ExactFloat::kMinExp - 1 + a_exp, ExactFloat::kMaxExp + 1 - a_exp); // Now modify the exponent and check for overflow/underflow. ExactFloat r = a; r.bn_exp_ += exp; r.Canonicalize(); return r; } ExactFloat scalbln(const ExactFloat& a, long exp) { // Clamp the exponent to the range of "int" in order to avoid truncation. // NOLINTNEXTLINE(runtime/int, google-runtime-int) exp = std::clamp(exp, INT_MIN, INT_MAX); return ldexp(a, static_cast(exp)); } int ilogb(const ExactFloat& a) { if (a.is_zero()) return FP_ILOGB0; if (isinf(a)) return INT_MAX; if (isnan(a)) return FP_ILOGBNAN; // a.exp() assumes the significand is in the range [0.5, 1). return a.exp() - 1; } ExactFloat logb(const ExactFloat& a) { if (a.is_zero()) return ExactFloat::Infinity(-1); if (isinf(a)) return ExactFloat::Infinity(+1); // Even if a < 0. if (isnan(a)) return a; // exp() assumes the significand is in the range [0.5,1). return ExactFloat(a.exp() - 1); } ExactFloat ExactFloat::Unimplemented() { ABSL_LOG(FATAL) << "Unimplemented ExactFloat method called"; return NaN(); } } // namespace exactfloat src/s2/util/math/exactfloat/exactfloat.h000066400000000000000000000623071524103652300205450ustar00rootroot00000000000000// Copyright 2009 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) // // ExactFloat is a multiple-precision floating point type that uses a custom // Bignum library for numerical calculations. It has the same interface as the // built-in "float" and "double" types, but only supports the subset of // operators and intrinsics where it is possible to compute the result exactly. // So for example, ExactFloat supports addition and multiplication but not // division (since in general, the quotient of two floating-point numbers cannot // be represented exactly). Exact arithmetic is useful for geometric // algorithms, especially for disambiguating cases where ordinary // double-precision arithmetic yields an uncertain result. // // ExactFloat was originally based on OpenSSL's Bignum library, but has been // updated to use a custom implementation to remove external dependencies. // // ExactFloat has the following features: // // - It uses the same syntax as the built-in "float" and "double" // types, for example: x += 4 + fabs(2*y*y - z*z). There are a few // differences (see below), but the syntax is compatible enough so that // ExactFloat can be used as a template argument to templatized classes // such as Vector2, VectorN, Matrix3x3, etc. // // - Results are not rounded; instead, precision is increased so that the // result can be represented exactly. An inexact result is returned only // in the case of underflow or overflow (yielding signed zero or infinity // respectively), or if the maximum allowed precision is exceeded (yielding // NaN). ExactFloat uses IEEE 754-2008 rules for handling infinities, NaN, // rounding to integers, etc. // // - ExactFloat only supports calculations where the result can be // represented exactly. Therefore it supports intrinsics such as fabs() // but not transcendentals such as sin(), sqrt(), etc. // // Syntax Compatibility with "float" and "double" // ---------------------------------------------- // // ExactFloat supports a subset of the operators and intrinsics for the // built-in "double" type. (Thus it supports fabs() but not fabsf(), for // example.) The syntax is different only in the following cases: // // - Explicit conversion to double is supported, but casts and implicit // conversions to other built-in types (including "bool") are not. // So for example, the following will not compile: // // ExactFloat x = 7.5; // double y = x; // ERROR: use static_cast(x) instead // long z = x; // ERROR: use static_cast(x) or // // lround(trunc(x)) // q = static_cast(x); // ERROR: use static_cast(x) or // // lround(trunc(x)) // if (x) { ... } // ERROR: use (x != 0) instead // // - The floating-point classification functions (isfinite, isnormal, isnan, // isinf, fpclassify) are supported. // // ExactFloat x; // if (isnan(x)) { ... } // if (isinf(x)) { ... } // // Using ExactFloat with Vector3, etc. // ----------------------------------- // // ExactFloat can be used with templatized classes such as Vector2 and Vector3 // (see "util/math/vector.h"). // // Precision Semantics // ------------------- // // Unlike MPFloat, ExactFloat does not allow a maximum precision to be // specified (it is always unbounded). Therefore it does not have any of the // corresponding constructors. // // The current precision of an ExactFloat (i.e., the number of bits in its // mantissa) is returned by prec(). The precision is increased as necessary // so that the result of every operation can be represented exactly. #ifndef S2_UTIL_MATH_EXACTFLOAT_EXACTFLOAT_H_ #define S2_UTIL_MATH_EXACTFLOAT_EXACTFLOAT_H_ #include #include #include #include #include #include #include "s2/util/math/exactfloat/bignum.h" namespace exactfloat { class ExactFloat { public: // The following limits are imposed by OpenSSL. // The maximum exponent supported. If a value has an exponent larger than // this, it is replaced by infinity (with the appropriate sign). static constexpr int kMaxExp = 200 * 1000 * 1000; // About 10**(60 million) // The minimum exponent supported. If a value has an exponent less than // this, it is replaced by zero (with the appropriate sign). static constexpr int kMinExp = -kMaxExp; // About 10**(-60 million) // The maximum number of mantissa bits supported. If a value has more // mantissa bits than this, it is replaced with NaN. (It is expected that // users of this class will never want this much precision.) static constexpr int kMaxPrec = 64 << 20; // About 20 million digits // Rounding modes. kRoundTiesToEven and kRoundTiesAwayFromZero both round // to the nearest representable value unless two values are equally close. // In that case kRoundTiesToEven rounds to the nearest even value, while // kRoundTiesAwayFromZero always rounds away from zero. enum RoundingMode { kRoundTiesToEven, kRoundTiesAwayFromZero, kRoundTowardZero, kRoundAwayFromZero, kRoundTowardPositive, kRoundTowardNegative }; ///////////////////////////////////////////////////////////////////////////// // Constructors // The default constructor initializes the value to zero. (The initial // value must be zero rather than NaN for compatibility with the built-in // float types.) inline ExactFloat() = default; // Construct an ExactFloat from a "double". The constructor is implicit so // that this class can be used as a replacement for "float" or "double" in // templatized libraries. (With an explicit constructor, code such as // "ExactFloat f = 2.5;" would not compile.) All double-precision values are // supported, including denormalized numbers, infinities, and NaNs. ExactFloat(double v); // NOLINT(google-explicit-constructor) // Construct an ExactFloat from an "int". Note that in general, ints are // automatically converted to doubles and so would be handled by the // constructor above. However, the particular argument (0) would be // ambiguous; the compiler wouldn't know whether to treat it as a "double" or // "const char*" (since 0 is a valid null pointer constant). Adding an "int" // constructor solves this problem. // // We do not provide constructors for "unsigned", "long", "unsigned long", // "long long", or "unsigned long long", since these types are not typically // used in floating-point calculations and it is safer to require them to be // explicitly cast. ExactFloat(int v); // NOLINT(google-explicit-constructor) // Construct an ExactFloat from a string (such as "1.2e50"). Requires that // the value is exactly representable as a floating-point number (so for // example, "0.125" is allowed but "0.1" is not). explicit ExactFloat(const char* s) { Unimplemented(); } ///////////////////////////////////////////////////////////////////// // Constants // // As an alternative to the constants below, you can also just use the // constants defined in , for example: // // ExactFloat x = NAN, y = -INFINITY; // Return an ExactFloat equal to positive zero (if sign >= 0) or // negative zero (if sign < 0). static ExactFloat SignedZero(int sign); // Return an ExactFloat equal to positive infinity (if sign >= 0) or // negative infinity (if sign < 0). static ExactFloat Infinity(int sign); // Return an ExactFloat that is NaN (Not-a-Number). static ExactFloat NaN(); ///////////////////////////////////////////////////////////////////////////// // Accessor Methods // Return the maximum precision of the ExactFloat. This method exists only // for compatibility with MPFloat. int max_prec() const { return kMaxPrec; } // Return the actual precision of this ExactFloat (the current number of // bits in its mantissa). Returns 0 for non-normal numbers such as NaN. int prec() const; // Return the exponent of this ExactFloat given that the mantissa is in the // range [0.5, 1). It is an error to call this method if the value is zero, // infinity, or NaN. int exp() const; // Set the value of the ExactFloat to +0 (if sign >= 0) or -0 (if sign < 0). void set_zero(int sign); // Set the value of the ExactFloat to positive infinity (if sign >= 0) or // negative infinity (if sign < 0). void set_inf(int sign); // Set the value of the ExactFloat to NaN (Not-a-Number). void set_nan(); // Classification functions. These are similar to the std::is* functions. friend int fpclassify(ExactFloat const& x); // Return true if this value is infinity (positive or negative). friend inline bool isinf(ExactFloat const& x); // Return true if this value is NaN (Not-a-Number). friend inline bool isnan(ExactFloat const& x); // Return true if this value is a normal floating-point number. Non-normal // values (zero, infinity, and NaN) often need to be handled separately // because they are represented using special exponent values and their // mantissa is not defined. friend inline bool isnormal(ExactFloat const& x); // Return true if this value is a normal floating-point number or zero, // i.e. it is not infinity or NaN. friend inline bool isfinite(ExactFloat const& x); // Return true if the sign bit is set (this includes negative zero). friend inline bool signbit(ExactFloat const& x); // Additional classification functions with no std:: equivalents. // Return true if this value is zero (including negative zero). inline bool is_zero() const; // Return +1 if this ExactFloat is positive, -1 if it is negative, and 0 // if it is zero or NaN. Note that unlike sign_bit(), sgn() returns 0 for // both positive and negative zero. inline int sgn() const; ///////////////////////////////////////////////////////////////////////////// // Conversion Methods // // Note that some conversions are defined as functions further below, // e.g. to convert to an integer you can use lround(), llrint(), etc. // Round to double precision. Note that since doubles have a much smaller // exponent range than ExactFloats, very small values may be rounded to // (positive or negative) zero, and very large values may be rounded to // infinity. // // It is very important to make an explicit conversion rather than an // implicit one, because otherwise there would be a silent loss of precision // whenever some desired operator or function happens not to be implemented. // For example, if fabs() were not implemented and "x" and "y" were // ExactFloats, then x = fabs(y) would silently convert "y" to a "double", // take its absolute value, and convert it back to an ExactFloat. explicit operator double() const; // Return a human-readable string such that if two values with the same // precision are different, then their string representations are different. // The format is similar to printf("%g"), except that the number of // significant digits depends on the precision (with a minimum of 10). // Trailing zeros are stripped (just like "%g"). // // Note that if two values have different precisions, they may have the same // ToString() value even though their values are slightly different. If you // need to distinguish such values, use ToUniqueString() instead. std::string ToString() const; // Return a string formatted according to printf("%Ng") where N is the given // maximum number of significant digits. std::string ToStringWithMaxDigits(int max_digits) const; // Return a human-readable string such that if two ExactFloats have different // values, then their string representations are always different. This // method is useful for debugging. The string has the form "value", // where "prec" is the actual precision of the ExactFloat (e.g., "0.215<50>"). std::string ToUniqueString() const; // Return an upper bound on the number of significant digits required to // distinguish any two floating-point numbers with the given precision when // they are formatted as decimal strings in exponential format. static int NumSignificantDigitsForPrec(int prec); // Output the ExactFloat in human-readable format, e.g. for logging. friend std::ostream& operator<<(std::ostream& o, ExactFloat const& f) { return o << f.ToString(); } ///////////////////////////////////////////////////////////////////////////// // Other Methods // Round the ExactFloat so that its mantissa has at most "max_prec" bits // using the given rounding mode. Requires "max_prec" to be at least 2 // (since kRoundTiesToEven doesn't make sense with fewer bits than this). ExactFloat RoundToMaxPrec(int max_prec, RoundingMode mode) const; ///////////////////////////////////////////////////////////////////////////// // Operators // Unary plus. ExactFloat operator+() const { return *this; } // Unary minus. ExactFloat operator-() const; // Addition. friend ExactFloat operator+(const ExactFloat& a, const ExactFloat& b); // Subtraction. friend ExactFloat operator-(const ExactFloat& a, const ExactFloat& b); // Multiplication. friend ExactFloat operator*(const ExactFloat& a, const ExactFloat& b); // Division is not implemented because the result cannot be represented // exactly in general. Doing this properly would require extending all the // operations to support rounding to a specified precision. // Arithmetic assignment operators (+=, -=, *=). ExactFloat& operator+=(const ExactFloat& b) { return (*this = *this + b); } ExactFloat& operator-=(const ExactFloat& b) { return (*this = *this - b); } ExactFloat& operator*=(const ExactFloat& b) { return (*this = *this * b); } // Comparison operators (==, !=, <, <=, >, >=). friend bool operator==(const ExactFloat& a, const ExactFloat& b); friend bool operator<(const ExactFloat& a, const ExactFloat& b); // These don't need to be friends but are declared here for completeness. inline friend bool operator!=(const ExactFloat& a, const ExactFloat& b); inline friend bool operator<=(const ExactFloat& a, const ExactFloat& b); inline friend bool operator>(const ExactFloat& a, const ExactFloat& b); inline friend bool operator>=(const ExactFloat& a, const ExactFloat& b); ///////////////////////////////////////////////////////////////////// // Math Intrinsics // // The math intrinsics currently supported by ExactFloat are listed below. // Except as noted, they behave identically to the usual std:: functions // except that they have greater precision. See the man pages for more // information. //////// Miscellaneous simple arithmetic functions. // Absolute value. friend ExactFloat fabs(const ExactFloat& a); friend ExactFloat abs(const ExactFloat& a); // Maximum of two values. friend ExactFloat fmax(const ExactFloat& a, const ExactFloat& b); // Minimum of two values. friend ExactFloat fmin(const ExactFloat& a, const ExactFloat& b); // Positive difference: max(a - b, 0). friend ExactFloat fdim(const ExactFloat& a, const ExactFloat& b); //////// Integer rounding functions that return ExactFloat values. // Round up to the nearest integer. friend ExactFloat ceil(const ExactFloat& a); // Round down to the nearest integer. friend ExactFloat floor(const ExactFloat& a); // Round to the nearest integer not larger in absolute value. // For example: f(-1.9) = -1, f(2.9) = 2. friend ExactFloat trunc(const ExactFloat& a); // Round to the nearest integer, rounding halfway cases away from zero. // For example: f(-0.5) = -1, f(0.5) = 1, f(1.5) = 2, f(2.5) = 3. friend ExactFloat round(const ExactFloat& a); // Round to the nearest integer, rounding halfway cases to an even integer. // For example: f(-0.5) = 0, f(0.5) = 0, f(1.5) = 2, f(2.5) = 2. friend ExactFloat rint(const ExactFloat& a); // A synonym for rint(). friend ExactFloat nearbyint(const ExactFloat& a) { return rint(a); } //////// Integer rounding functions that return C++ integer types. // Like rint(), but rounds to the nearest "long" value. Returns the // minimum/maximum possible integer if the value is out of range. // NOLINTNEXTLINE(runtime/int, google-runtime-int) friend long lrint(const ExactFloat& a); // Like rint(), but rounds to the nearest "long long" value. Returns the // minimum/maximum possible integer if the value is out of range. // NOLINTNEXTLINE(runtime/int, google-runtime-int) friend long long llrint(const ExactFloat& a); // Like round(), but rounds to the nearest "long" value. Returns the // minimum/maximum possible integer if the value is out of range. // NOLINTNEXTLINE(runtime/int, google-runtime-int) friend long lround(const ExactFloat& a); // Like round(), but rounds to the nearest "long long" value. Returns the // minimum/maximum possible integer if the value is out of range. // NOLINTNEXTLINE(runtime/int, google-runtime-int) friend long long llround(const ExactFloat& a); //////// Remainder functions. // The remainder of dividing "a" by "b", where the quotient is rounded toward // zero to the nearest integer. Similar to (a - trunc(a / b) * b). friend ExactFloat fmod(const ExactFloat& a, const ExactFloat& b) { // Note that it is possible to implement this operation exactly, it just // hasn't been done. return Unimplemented(); } // The remainder of dividing "a" by "b", where the quotient is rounded to the // nearest integer, rounding halfway cases to an even integer. Similar to // (a - rint(a / b) * b). friend ExactFloat remainder(const ExactFloat& a, const ExactFloat& b) { // Note that it is possible to implement this operation exactly, it just // hasn't been done. return Unimplemented(); } // A synonym for remainder(). friend ExactFloat drem(const ExactFloat& a, const ExactFloat& b) { return remainder(a, b); } // Break the argument "a" into integer and fractional parts, each of which // has the same sign as "a". The fractional part is returned, and the // integer part is stored in the output parameter "i_ptr". Both output // values are set to have the same maximum precision as "a". friend ExactFloat modf(const ExactFloat& a, ExactFloat* i_ptr) { // Note that it is possible to implement this operation exactly, it just // hasn't been done. return Unimplemented(); } //////// Floating-point manipulation functions. // Return an ExactFloat with the magnitude of "a" and the sign bit of "b". // (Note that an IEEE zero can be either positive or negative.) friend ExactFloat copysign(const ExactFloat& a, const ExactFloat& b); // Convert "a" to a normalized fraction in the range [0.5, 1) times a power // of two. Return the fraction and set "exp" to the exponent. If "a" is // zero, infinity, or NaN then return "a" and set "exp" to zero. friend ExactFloat frexp(const ExactFloat& a, int* exp); // Return "a" multiplied by 2 raised to the power "exp". friend ExactFloat ldexp(const ExactFloat& a, int exp); // A synonym for ldexp(). friend ExactFloat scalbn(const ExactFloat& a, int exp) { return ldexp(a, exp); } // A version of ldexp() where "exp" is a long integer. // NOLINTNEXTLINE(runtime/int, google-runtime-int) friend ExactFloat scalbln(const ExactFloat& a, long exp); // Convert "a" to a normalized fraction in the range [1,2) times a power of // two, and return the exponent value as an integer. This is equivalent to // lrint(floor(log2(fabs(a)))) but it is computed more efficiently. Returns // the constants documented in the man page for zero, infinity, or NaN. friend int ilogb(const ExactFloat& a); // Convert "a" to a normalized fraction in the range [1,2) times a power of // two, and return the exponent value as an ExactFloat. This is equivalent to // floor(log2(fabs(a))) but it is computed more efficiently. friend ExactFloat logb(const ExactFloat& a); protected: using Bignum = exactfloat_internal::Bignum; // Non-normal numbers are represented using special exponent values and a // mantissa of zero. Do not change these values; methods such as // is_normal() make assumptions about their ordering. Non-normal numbers // can have either a positive or negative sign (including zero and NaN). static constexpr int32_t kExpNaN = INT_MAX; static constexpr int32_t kExpInfinity = INT_MAX - 1; static constexpr int32_t kExpZero = INT_MAX - 2; // Normal numbers are represented as (sign_ * bn_ * (2 ** bn_exp_)), where: // - sign_ is either +1 or -1 // - bn_ is a Bignum with a positive value // - bn_exp_ is the base-2 exponent applied to bn_. // // bn_ stores the magnitude for the mantissa of the floating point value. We // store a sign bit here separately from bn_ so that functions like exp() are // easier to reason about (as the sign would flip depending on whether the // exponent were odd or even). int32_t sign_ = 1; int32_t bn_exp_ = kExpZero; Bignum bn_; // A standard IEEE "double" has a 53-bit mantissa consisting of a 52-bit // fraction plus an implicit leading "1" bit. static constexpr int kDoubleMantissaBits = 53; // Convert an ExactFloat with no more than 53 bits in its mantissa to a // "double". This method handles non-normal values (NaN, etc). double ToDoubleHelper() const; // Round an ExactFloat so that it is a multiple of (2 ** bit_exp), using the // given rounding mode. ExactFloat RoundToPowerOf2(int bit_exp, RoundingMode mode) const; // Convert the ExactFloat to a decimal value of the form 0.ddd * (10 ** x), // with at most "max_digits" significant digits (trailing zeros are removed). // Set (*digits) to the ASCII digits (just the "ddd" portion, without leading // "0.") and return the decimal exponent "x". int GetDecimalDigits(int max_digits, std::string* digits) const; // Return a_sign * fabs(a) + b_sign * fabs(b). Used to implement addition // and subtraction. static ExactFloat SignedSum(int a_sign, const ExactFloat* a, int b_sign, const ExactFloat* b); // Convert an ExactFloat to its canonical form. Underflow results in signed // zero, overflow results in signed infinity, and precision overflow results // in NaN. A zero mantissa is converted to the canonical zero value with // the given sign; otherwise the mantissa is normalized so that its low bit // is 1. Non-normal numbers are left unchanged. void Canonicalize(); // Scale the mantissa of this ExactFloat so that it has the same bn_exp_ as // "b", then return -1, 0, or 1 according to whether the scaled mantissa is // less, equal, or greater than the mantissa of "b". Requires that both // values are normal. int ScaleAndCompare(const ExactFloat& b) const; // Return true if the magnitude of this ExactFloat is less than the // magnitude of "b". Requires that neither value is NaN. bool UnsignedLess(const ExactFloat& b) const; // Return an ExactFloat with the magnitude of this ExactFloat and the given // sign. (Similar to copysign, except that the sign is given explicitly // rather than being copied from another ExactFloat.) inline ExactFloat CopyWithSign(int sign) const; // Convert an ExactFloat to an integer of type "T" using the given rounding // mode. The type "T" must be signed. Returns the largest possible integer // for NaN, and clamps out of range values to the largest or smallest // possible values. template T ToInteger(RoundingMode mode) const; // Log a fatal error message (used for unimplemented methods). static ExactFloat Unimplemented(); }; ///////////////////////////////////////////////////////////////////////// // Implementation details follow: inline bool isinf(ExactFloat const& x) { return x.bn_exp_ == ExactFloat::kExpInfinity; } inline bool isnan(ExactFloat const& x) { return x.bn_exp_ == ExactFloat::kExpNaN; } inline bool isnormal(ExactFloat const& x) { return x.bn_exp_ < ExactFloat::kExpZero; } inline bool isfinite(ExactFloat const& x) { return x.bn_exp_ <= ExactFloat::kExpZero; } inline bool signbit(ExactFloat const& x) { return x.sign_ < 0; } inline bool ExactFloat::is_zero() const { return bn_exp_ == kExpZero; } inline int ExactFloat::sgn() const { return (isnan(*this) || is_zero()) ? 0 : sign_; } inline bool operator!=(const ExactFloat& a, const ExactFloat& b) { return !(a == b); } inline bool operator<=(const ExactFloat& a, const ExactFloat& b) { // NaN is unordered compared to everything, including itself. if (isnan(a) || isnan(b)) return false; return !(b < a); } inline bool operator>(const ExactFloat& a, const ExactFloat& b) { return b < a; } inline bool operator>=(const ExactFloat& a, const ExactFloat& b) { return b <= a; } inline ExactFloat ExactFloat::CopyWithSign(int sign) const { ExactFloat r = *this; r.sign_ = sign; return r; } } // namespace exactfloat #endif // S2_UTIL_MATH_EXACTFLOAT_EXACTFLOAT_H_ src/s2/util/math/exactfloat/exactfloat_test.cc000066400000000000000000001101161524103652300217320ustar00rootroot00000000000000// Copyright 2009 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Author: ericv@google.com (Eric Veach) #include "s2/util/math/exactfloat/exactfloat.h" #include #include #include #include #include #include #include #include #include #include #include "absl/base/casts.h" #include "absl/base/macros.h" #include "absl/base/no_destructor.h" #include "absl/log/absl_check.h" #include "absl/log/absl_log.h" #include "absl/random/random.h" #include "s2/util/math/vector.h" namespace { using ::exactfloat::ExactFloat; // Usually, these would be found by ADL, but we use them as function pointers. using ::exactfloat::isfinite; using ::exactfloat::isinf; using ::exactfloat::isnan; using ::exactfloat::isnormal; using ::exactfloat::signbit; // To check the handling of boundary cases (NaN, infinities, out of range, // overflow, etc), we check the ExactFloat versions of all the operators and // functions against the glibc and/or hardware versions. // // The results are not always identical for several reasons. The main reasons // are that ExactFloat has a much higher precision, a much larger exponent // range, and does not round. But some differences are due to bugs in glibc. // The worst of these are fixed below. #ifndef DONT_FIX_GLIBC_MATH_FUNCTIONS // There are a few cases where the glibc math functions return an incorrect // result. We handle this by defining our own corrected versions here. // // Note that these corrections are only known to be sufficient on exactly one // platform, namely "--march=k8 --mfpmath=sse" with glibc 2.3.6. Glibc // undoubtedly has other bugs in other platforms and versions which would need // to be corrected separately. double fdim(double a, double b) { // ::fdim(-inf, -inf) incorrectly returns NaN. The result should be zero // because fdim is defined to return 0 when a <= b, and IEEE 754 defines // -inf to be equal to itself (even though (-inf) - (-inf) is NaN). // // Note that ::fdim(inf, inf) does return 0 (the correct result). if (a == b) return 0; return ::fdim(a, b); } double fmax(double a, double b) { // fmax(0, -0) returns -0 rather than +0. This is technically not a bug, // but it is different from (and inferior to) the MPFloat behavior. if (a == 0 && b == 0) return a + b; return ::fmax(a, b); } double fmin(double a, double b) { // fmin(-0, 0) returns +0 rather than -0. This is technically not a bug, // but it is different from (and inferior to) the MPFloat behavior. if (a == 0 && b == 0 && (std::signbit(a) || std::signbit(b))) { return copysign(0, -1); } return ::fmin(a, b); } double logb(double a) { // If "a" is denormalized, logb() is supposed to return the exponent that // "a" would have if it were normalized. (But it doesn't.) if (a != 0 && fabs(a) < std::numeric_limits::min()) { return ::logb(scalbn(a, 100)) - 100; } return ::logb(a); } double ldexp(double a, int exp) { // ldexp() incorrectly returns infinity rather than zero when the // "a" is finite and "exp" is a very large negative value. double r = ::ldexp(a, exp); if (std::isinf(r) && !std::isinf(a) && exp < 0) { return copysign(0, r); } return r; } double scalbn(double a, int exp) { return ldexp(a, exp); // See ldexp(). } double scalbln(double a, long exp) { // Clamp the exponent to the range of "int" in order to avoid truncation. exp = std::max(static_cast(INT_MIN), std::min(static_cast(INT_MAX), exp)); return ldexp(a, exp); // See ldexp(). } // The C standard does not specify the result of converting a floating-point // number to an integer if the argument is NaN or out of range. This applies // to both static_cast and functions such as lrint, lround, etc. // // With the glibc/Intel platform tested here, these conversions return the // minimum possible value of the result type. (Except if the argument is a // constant, in which case gcc converts NaN to zero and clamps out of range // arguments to the minimum or maximum possible value.) // // Here we fix the rounding functions to match MPFloat, which clamps out of // range values and returns the maximum possible value for NaN. #define FIX_INT_ROUNDING(T, fname) \ T fname(double a) { \ if (std::isnan(a)) return std::numeric_limits::max(); \ if (a <= std::numeric_limits::min()) \ return std::numeric_limits::min(); \ if (a >= std::numeric_limits::max()) \ return std::numeric_limits::max(); \ return ::fname(a); \ } FIX_INT_ROUNDING(long, lrint) FIX_INT_ROUNDING(long, lround) FIX_INT_ROUNDING(long long, llrint) FIX_INT_ROUNDING(long long, llround) #endif // DONT_FIX_GLIBC_MATH_FUNCTIONS // A list of double-precision constants to use as arguments when evaluating // math intrinsics. The negated values of these constants are used as well, // so only one constant with a given absolute value needs to be listed. constexpr double kSpecialUnsignedDoubleValues[] = { std::numeric_limits::quiet_NaN(), // Minimum and maximum values of various relevant C++ types. std::numeric_limits::infinity(), std::numeric_limits::max(), std::numeric_limits::min(), std::numeric_limits::denorm_min(), static_cast(std::numeric_limits::max()), static_cast(std::numeric_limits::min()), static_cast(std::numeric_limits::max()), static_cast(std::numeric_limits::min()), static_cast(std::numeric_limits::max()), 0, // Small and large values that are not quite minimums or maximums. 1.23e-300, 1e-20, 1e20, 1.23e300, // Interesting values for trigonometric, exponential, and logarithm // functions. 2 * M_PI, M_PI, M_PI_2, M_PI_4, M_E, M_LN2, // Positive and negative powers of two. 1 << 30, 256, 16, 2, 1, 0.5, 1.0 / 256, 1.0 / (1 << 30), // Interesting values for integer rounding functions. 1.5, 2.5, 3.5, // Miscellaneous integer and non-integer "ordinary" values. 42, 7, 5, 0.3, 0.17, }; class ExactFloatTest : public ::testing::Test { public: // Initialize the list of constants to be used for testing intrinsics. static void SetUpTestSuite() { ABSL_CHECK(special_double_values_->empty()); for (double d : kSpecialUnsignedDoubleValues) { special_double_values_->push_back(d); // Glibc and MPFloat handle negative NaN values differently. To avoid // discrepancies, we only test positively-signed NaN values. if (!std::isnan(d)) { special_double_values_->push_back(-d); } } } static void TearDownTestSuite() { special_double_values_->clear(); } // Return the difference measured in ulps (units in the last place) between // two floating-point values. Return 0 if the values are equal or both are // NaN, and return the largest possible uint64_t if exactly one value is NaN. // Note that +0 and -0 are equal (i.e., they differ by 0 ulps), and that the // smallest positive and negative values differ by 2 ulps. Infinity is one // ulp larger than the largest finite number. static uint64_t GetErrorUlps(double a, double b) { if (std::isnan(a) && std::isnan(b)) return 0; if (std::isnan(a) || std::isnan(b)) { return std::numeric_limits::max(); } // Floating-point numbers are arranged so that for numbers of the same // sign, the difference in ulps is just the difference between the two // numbers viewed as 64-bit unsigned integers. uint64_t a_bits = absl::bit_cast(a); uint64_t b_bits = absl::bit_cast(b); if (std::signbit(a) == std::signbit(b)) { return (a_bits > b_bits) ? (a_bits - b_bits) : (b_bits - a_bits); } // For numbers of opposite sign, we take the difference in ulps between // each number and the zero of the same sign, and add them together. a_bits ^= static_cast(1) << 63; return a_bits + b_bits; } // Return true if the difference between "expected" and "actual" is at most // the given number of ulps (units in the last place). The two values are // also required to have the same sign bit unless they are both NaN. (So for // example, +0 and -0 are not equivalent.) static bool IsExpected(double expected, double actual, uint64_t ulps) { // We require the sign bit to match unless the values are NaN. if (!std::isnan(expected) && std::signbit(expected) != std::signbit(actual)) { return false; } return GetErrorUlps(expected, actual) <= ulps; } // Expect "actual" to have the given value when converted to a "double". // Two values are considered equivalent if they have the same bit pattern or // they are both NaN. (So for example, +0 and -0 are not equivalent.) void ExpectSame(double expected, const ExactFloat& xf_actual) { double actual = static_cast(xf_actual); if (std::isnan(expected)) { EXPECT_TRUE(std::isnan(actual)); } else { // Keep the ugly std::signbit() macro out of the error messages. bool expected_sign = std::signbit(expected); bool actual_sign = std::signbit(actual); EXPECT_EQ(expected_sign, actual_sign); EXPECT_EQ(expected, actual); } } // Like ExpectSame() but also check that "actual" has the expected precision. void ExpectSameWithPrec(double expected_value, int expected_prec, const ExactFloat& xf_actual) { ExpectSame(expected_value, xf_actual); EXPECT_EQ(expected_prec, xf_actual.prec()); } // Log an error when a math intrinsic does not return the expected result. static void AddMathcallFailure(const testing::Message& call_msg, double expected, double actual) { ADD_FAILURE() << call_msg << "\nExpected (glibc): " << ExactFloat(expected) << "\nActual (ExactFloat): " << ExactFloat(actual) << "\nError: " << GetErrorUlps(expected, actual) << " ulps"; } protected: // Given two versions "f" and "mp_f" of the unary function called "fname", // check that their results agree to within the given number of ulps for a // range of test arguments. void TestMathcall1(const char* fname, double f(double), ExactFloat mp_f(const ExactFloat&), uint64_t ulps) { for (double a : *special_double_values_) { double expected = f(a); double actual = static_cast(mp_f(ExactFloat(a))); if (!IsExpected(expected, actual, ulps)) { AddMathcallFailure(testing::Message() << fname << "(" << ExactFloat(a) << ")", expected, actual); } } } // Given two versions "f" and "mp_f" of the binary function called "fname", // check that their results agree to within the given number of ulps for a // range of test arguments. void TestMathcall2(const char* fname, double f(double, double), ExactFloat mp_f(const ExactFloat&, const ExactFloat&), uint64_t ulps) { for (double a : *special_double_values_) { for (double b : *special_double_values_) { double expected = f(a, b); double actual = static_cast(mp_f(ExactFloat(a), ExactFloat(b))); if (!IsExpected(expected, actual, ulps)) { AddMathcallFailure(testing::Message() << fname << "(" << ExactFloat(a) << ", " << ExactFloat(b) << ")", expected, actual); } } } } // Given a one-argument function "f" and a zero-argument ExactFloat member // function "mp_f", check that they return the same result on a range of // test arguments. template void TestFn(const char* fname, ResultType f_dbl(double), ResultType f_xf(const ExactFloat&)) { for (double a : *special_double_values_) { ResultType expected = f_dbl(a); ResultType actual = f_xf(ExactFloat(a)); if (expected != actual) { AddMathcallFailure(testing::Message() << ExactFloat(a) << "." << fname << "()", expected, actual); } } } // Given two versions "f" and "mp_f" of a unary function called "fname" that // returns the integer type ResultType, check that they return the same // value for a range of test arguments. template void TestIntMathcall1(const char* fname, ResultType f(double), ResultType mp_f(const ExactFloat&)) { for (double a : *special_double_values_) { ResultType expected = f(a); ResultType actual = mp_f(ExactFloat(a)); if (actual != expected) { AddMathcallFailure( testing::Message() << fname << "(" << ExactFloat(a) << ")", static_cast(expected), static_cast(actual)); } } } // Given two versions "f" and "mp_f" of a function called "fname" that has // an interface similar to ldexp() (i.e., with one "double" argument and one // integer argument), check that they return the same result for a range of // test arguments. "ExpType" is the type of the integer argument. template void TestLdexpCall(const char* fname, double f(double, ExpType), ExactFloat mp_f(const ExactFloat&, ExpType)) { static constexpr ExpType kUnsignedExpValues[] = { // Doesn't test with numeric_limits::min() because it's // undefined // to negate the min value of a signed number. std::numeric_limits::max(), 0, 1, 2, 3, 10, 20, 50, 100, 200, 500, 999, 1022, 1023, 1024, 1073, 1074, 2046, 2047, 2048, 4096, 1000000, }; for (double a : *special_double_values_) { for (ExpType unsigned_exp : kUnsignedExpValues) { for (int sign : {-1, +1}) { ExpType exp = sign * unsigned_exp; double expected = f(a, exp); double actual = static_cast(mp_f(ExactFloat(a), exp)); if (!IsExpected(expected, actual, 0)) { AddMathcallFailure(testing::Message() << fname << "(" << ExactFloat(a) << ", " << exp << ")", expected, actual); } } } } } private: // Uses `isnan` in initialization; this can be `constexpr` when we support // C++23; `isnan` is not `constexpr` until then. static absl::NoDestructor> special_double_values_; }; absl::NoDestructor> ExactFloatTest::special_double_values_; TEST_F(ExactFloatTest, GetErrorUlps) { // Verify some of the assertions made by GetErrorUlps(). EXPECT_EQ(0, GetErrorUlps(NAN, -NAN)); EXPECT_EQ(0, GetErrorUlps(0, copysign(0, -1))); EXPECT_EQ(2, GetErrorUlps(std::numeric_limits::denorm_min(), -std::numeric_limits::denorm_min())); EXPECT_EQ(1, GetErrorUlps(std::numeric_limits::max(), INFINITY)); EXPECT_EQ(std::numeric_limits::max(), GetErrorUlps(0, NAN)); } TEST_F(ExactFloatTest, Constructors) { // Default constructor. ExactFloat a; ExpectSameWithPrec(0.0, 0, a); // Construct an ExactFloat from the literal constant "0". It is necessary to // have an implicit constructor that takes an "int" argument for this to // work; otherwise the compiler thinks that "0" is ambiguous (it could be a // "double" or a "const char*"). ExactFloat a0 = 0; ExpectSameWithPrec(0.0, 0, a); // Implicit constructor from "double". ExactFloat b = 2.5; ExpectSameWithPrec(2.5, 3, b); // Implicit constructor from "int". ExactFloat c = -125; ExpectSameWithPrec(-125, 7, c); // Copy constructor. ExactFloat e = c; ExpectSameWithPrec(-125, 7, e); } TEST_F(ExactFloatTest, IntMinConstruction) { // Ensure that construction with INT_MIN works properly. ExactFloat f = INT_MIN; ExpectSame(INT_MIN, f); } TEST_F(ExactFloatTest, Constants) { EXPECT_TRUE(ExactFloat::SignedZero(+1).is_zero()); EXPECT_EQ(false, signbit(ExactFloat::SignedZero(+1))); EXPECT_TRUE(ExactFloat::SignedZero(-1).is_zero()); EXPECT_EQ(true, signbit(ExactFloat::SignedZero(-1))); EXPECT_TRUE(isinf(ExactFloat::Infinity(+1))); EXPECT_EQ(false, signbit(ExactFloat::Infinity(+1))); EXPECT_TRUE(isinf(ExactFloat::Infinity(-1))); EXPECT_EQ(true, signbit(ExactFloat::Infinity(-1))); EXPECT_TRUE(isnan(ExactFloat::NaN())); } TEST_F(ExactFloatTest, Accessors) { // A few quick checks of prec(), max_prec(), and exp(). ExactFloat x = 7.25; ExpectSameWithPrec(7.25, 5, x); EXPECT_EQ(3, x.exp()); EXPECT_EQ(ExactFloat::kMaxPrec, x.max_prec()); x = 255; ExpectSameWithPrec(255, 8, x); EXPECT_EQ(8, x.exp()); x = 256; ExpectSameWithPrec(256, 1, x); EXPECT_EQ(9, x.exp()); } TEST_F(ExactFloatTest, set_zero) { ExactFloat x = 5.0; EXPECT_FALSE(x.is_zero()); x.set_zero(+1); EXPECT_TRUE(x.is_zero()); ExpectSameWithPrec(0.0, 0, x); x.set_zero(-1); EXPECT_TRUE(x.is_zero()); ExpectSameWithPrec(copysign(0.0, -1), 0, x); } TEST_F(ExactFloatTest, set_inf) { ExactFloat x; EXPECT_FALSE(isinf(x)); x.set_inf(+1); EXPECT_TRUE(isinf(x)); ExpectSameWithPrec(INFINITY, 0, x); x.set_inf(-1); EXPECT_TRUE(isinf(x)); ExpectSameWithPrec(-INFINITY, 0, x); x = NAN; EXPECT_FALSE(isinf(x)); x = INFINITY; EXPECT_TRUE(isinf(x)); ExpectSameWithPrec(INFINITY, 0, x); x = -INFINITY; EXPECT_TRUE(isinf(x)); ExpectSameWithPrec(-INFINITY, 0, x); } TEST_F(ExactFloatTest, set_nan) { ExactFloat x; EXPECT_FALSE(isnan(x)); ExpectSameWithPrec(0.0, 0, x); x.set_nan(); EXPECT_TRUE(isnan(x)); ExpectSameWithPrec(NAN, 0, x); x = 2; EXPECT_FALSE(isnan(x)); x = NAN; EXPECT_TRUE(isnan(x)); ExpectSameWithPrec(NAN, 0, x); } TEST_F(ExactFloatTest, OperatorDouble) { EXPECT_EQ(0, static_cast(ExactFloat(0))); ExpectSame(copysign(0.0, -1), -ExactFloat(0)); EXPECT_EQ( std::numeric_limits::max(), static_cast(ExactFloat(std::numeric_limits::max()))); EXPECT_EQ( -std::numeric_limits::min(), static_cast(ExactFloat(-std::numeric_limits::min()))); EXPECT_EQ(std::numeric_limits::denorm_min(), static_cast( ExactFloat(std::numeric_limits::denorm_min()))); EXPECT_EQ(-12.7, static_cast(ExactFloat(-12.7))); EXPECT_EQ(M_PI, static_cast(ExactFloat(M_PI))); EXPECT_EQ(INFINITY, static_cast(ExactFloat(INFINITY))); EXPECT_EQ(-INFINITY, static_cast(ExactFloat(-INFINITY))); EXPECT_TRUE(std::isnan(static_cast(ExactFloat(NAN)))); } TEST_F(ExactFloatTest, ToString) { EXPECT_EQ("0.001", ExactFloat(0.001).ToString()); EXPECT_EQ("0.10000000000000001", ExactFloat(0.1).ToString()); EXPECT_EQ("0.001953125", ExactFloat(1. / 512).ToString()); EXPECT_EQ("1e-50", ExactFloat(1e-50).ToString()); EXPECT_EQ("1e-50", ExactFloat(1e-50).ToString()); EXPECT_EQ("0", ExactFloat(0).ToString()); EXPECT_EQ("nan", ExactFloat(NAN).ToString()); EXPECT_EQ("-inf", ExactFloat(-INFINITY).ToString()); EXPECT_EQ("65536", ExactFloat(65536).ToString()); EXPECT_EQ("1048576", ExactFloat(1 << 20).ToString()); EXPECT_EQ("1048575", ExactFloat((1 << 20) - 1).ToString()); EXPECT_EQ("1073741824", ExactFloat(1 << 30).ToString()); EXPECT_EQ("1073741823", ExactFloat((1 << 30) - 1).ToString()); EXPECT_EQ("1.099511628e+12", ExactFloat(pow(2, 40)).ToString()); EXPECT_EQ("1099511627775", ExactFloat(pow(2, 40) - 1).ToString()); EXPECT_EQ("1.606938044e+60", ExactFloat(pow(2, 200)).ToString()); EXPECT_EQ("1606938044258990275541962092341162602522202993782792835301375", (ExactFloat(pow(2, 200)) - 1).ToString()); EXPECT_EQ("3.1415926535897931", ExactFloat(M_PI).ToString()); // Verify that ToString implements kRoundTiesToEven (the same as glibc). EXPECT_EQ("0.62", ExactFloat(0.625).ToStringWithMaxDigits(2)); EXPECT_EQ("0.62", ExactFloat(0.625).ToStringWithMaxDigits(2)); EXPECT_EQ("1.88", ExactFloat(1.875).ToStringWithMaxDigits(3)); // Three digits are sufficient to distinguish any two numbers with 6-bit // mantissas, but up to four digits are required to distinguish two numbers // with 7-bit mantissas (e.g. 1016 and 1024). EXPECT_EQ(3, ExactFloat::NumSignificantDigitsForPrec(6)); EXPECT_EQ(4, ExactFloat::NumSignificantDigitsForPrec(7)); ABSL_LOG(INFO) << "Test of ExactFloat stream output: " << ExactFloat(1.23456); } TEST_F(ExactFloatTest, ToUniqueString) { // The following test demonstrates that ExactFloats with different values and // different precisions can generate the same ToString() value. ExactFloat value = 0.01; ExactFloat v1 = value.RoundToMaxPrec(33, ExactFloat::kRoundTiesToEven); ExactFloat v2 = value.RoundToMaxPrec(46, ExactFloat::kRoundTiesToEven); EXPECT_NE(v1, v2); EXPECT_EQ("0.01", v1.ToString()); EXPECT_EQ("0.01", v2.ToString()); EXPECT_EQ("0.01<33>", v1.ToUniqueString()); EXPECT_EQ("0.01<46>", v2.ToUniqueString()); } TEST_F(ExactFloatTest, RoundToMaxPrec) { // This method is used by the `operator double()` implementation and also the // rounding function such as trunc(), floor(), etc, so it is already pretty // well tested. We do a few other tests here. EXPECT_EQ(ExactFloat(pow(2, 500)), (ExactFloat(pow(2, 500)) - 1) .RoundToMaxPrec(2, ExactFloat::kRoundTiesToEven)); EXPECT_EQ(ExactFloat(pow(2, 500)), (ExactFloat(pow(2, 500)) - 1) .RoundToMaxPrec(499, ExactFloat::kRoundTiesToEven)); EXPECT_EQ(ExactFloat(pow(2, 500)) - 4, (ExactFloat(pow(2, 500)) - 3) .RoundToMaxPrec(499, ExactFloat::kRoundTiesToEven)); EXPECT_EQ(ExactFloat(pow(2, 500)) + 16, (ExactFloat(pow(2, 500)) + 1) .RoundToMaxPrec(497, ExactFloat::kRoundTowardPositive)); EXPECT_EQ(2.7, ExactFloat(2.7).RoundToMaxPrec(1000000, ExactFloat::kRoundTiesToEven)); } // Test the ExactFloat version of the unary operator "op" against the // corresponding C++ operator. #define TEST_MATHOP1(op_name, op) \ double op_name(double a) { return op(a); } \ ExactFloat mp_##op_name(const ExactFloat& a) { return op(a); } \ TEST_F(ExactFloatTest, op_name) { \ TestMathcall1(#op_name, op_name, mp_##op_name, 0); \ } TEST_MATHOP1(plus, +) TEST_MATHOP1(minus, -) // Test the ExactFloat version of the binary operator "op" against the // corresponding C++ operator. #define TEST_MATHOP2(op_name, op) \ double op_name(double a, double b) { return (a)op(b); } \ ExactFloat mp_##op_name(const ExactFloat& a, const ExactFloat& b) { \ return (a)op(b); \ } \ TEST_F(ExactFloatTest, op_name) { \ TestMathcall2(#op_name, op_name, mp_##op_name, 0); \ } TEST_MATHOP2(add, +); TEST_MATHOP2(subtract, -); TEST_MATHOP2(multiply, *); // Division is not defined. TEST_MATHOP2(equal, ==); TEST_MATHOP2(less, <); TEST_MATHOP2(greater, >); TEST_MATHOP2(not_equal, !=); TEST_MATHOP2(not_less, >=); TEST_MATHOP2(not_greater, <=); // Test the various assignment operators. #define TEST_ASSIGNOP(op_name, op) \ double op_name(double a, double b) { \ (a) op(b); \ return a; \ } \ ExactFloat mp_##op_name(const ExactFloat& a, const ExactFloat& b) { \ ExactFloat x = a; \ x op(b); \ return x; \ } \ TEST_F(ExactFloatTest, op_name) { \ TestMathcall2(#op_name, op_name, mp_##op_name, 0); \ } TEST_ASSIGNOP(assignment, =); TEST_ASSIGNOP(plus_equals, +=); TEST_ASSIGNOP(minus_equals, -=); TEST_ASSIGNOP(times_equals, *=); // Division is not defined. // Check that the ExactFloat and glibc versions of "func" always return the same // value to within the given number of ulps. #define TEST_MATHCALL1(func, ulps) \ /* We define a wrapper function around ExactFloat version of "func" */ \ /* so that we can take its address (gcc can't find it otherwise). */ \ ExactFloat mp_##func(const ExactFloat& a) { return func(a); } \ TEST_F(ExactFloatTest, func) { TestMathcall1(#func, func, mp_##func, ulps); } // Test all the unary math instrinsics (in the same order as the .h file). TEST_MATHCALL1(fabs, 0) TEST_MATHCALL1(ceil, 0) TEST_MATHCALL1(floor, 0) TEST_MATHCALL1(trunc, 0) TEST_MATHCALL1(rint, 0) TEST_MATHCALL1(nearbyint, 0) TEST_MATHCALL1(logb, 0) TEST_MATHCALL1(round, 0) // Check that the ExactFloat and glibc versions of "func" always return the // same value to within the given number of ulps. #define TEST_MATHCALL2(func, ulps) \ ExactFloat mp_##func(const ExactFloat& a, const ExactFloat& b) { \ return func(a, b); \ } \ TEST_F(ExactFloatTest, func) { TestMathcall2(#func, func, mp_##func, ulps); } // Test all the binary math instrinsics (in the same order as the .h file). TEST_MATHCALL2(fmax, 0) TEST_MATHCALL2(fmin, 0) TEST_MATHCALL2(fdim, 0) TEST_MATHCALL2(copysign, 0) // Check that the ExactFloat and glibc versions of "func" return the same // integer value. #define TEST_INTEGER_MATHCALL1(ResultType, func) \ ResultType mp_##func(const ExactFloat& a) { return func(a); } \ TEST_F(ExactFloatTest, func) { TestIntMathcall1(#func, func, mp_##func); } TEST_INTEGER_MATHCALL1(long, lrint); TEST_INTEGER_MATHCALL1(long long, llrint); TEST_INTEGER_MATHCALL1(long, lround); TEST_INTEGER_MATHCALL1(long long, llround); TEST_INTEGER_MATHCALL1(int, ilogb); //////////////////////////////////////////////////////////////////////////// // frexp(): Test using wrapper functions to check each result separately. double frexp_frac(double a) { int exp_part; return frexp(a, &exp_part); } int frexp_exp(double a) { int exp_part; (void)frexp(a, &exp_part); return exp_part; } ExactFloat mp_frexp_frac(const ExactFloat& a) { int exp_part; return frexp(a, &exp_part); } int mp_frexp_exp(const ExactFloat& a) { int exp_part; (void)frexp(a, &exp_part); return exp_part; } #if !defined(__wasm__) TEST_F(ExactFloatTest, frexp) { TestMathcall1("frexp_frac", frexp_frac, mp_frexp_frac, 0); TestIntMathcall1("frexp_exp", frexp_exp, mp_frexp_exp); } #endif //////////////////////////////////////////////////////////////////////////// // ldexp(), scalbn(), scalbln() #define TEST_LDEXP_CALL(ExpType, func) \ ExactFloat mp_##func(const ExactFloat& a, ExpType exp) { \ return func(a, exp); \ } \ TEST_F(ExactFloatTest, func) { TestLdexpCall(#func, func, mp_##func); } // Results are different on Apple platforms; it's not clear if it's an Apple // or glibc problem. #if !defined(__APPLE__) TEST_LDEXP_CALL(int, ldexp); TEST_LDEXP_CALL(int, scalbn); TEST_LDEXP_CALL(long, scalbln); #endif // Test a zero-argument ExactFloat member function against a corresponding // one-argument reference function. #define TEST_FN_VS_REF(ResultType, fn_xf, fn_dbl) \ TEST_F(ExactFloatTest, fn_xf) { TestFn(#fn_xf, fn_dbl, fn_xf); } // "Reference versions" of various zero-argument methods. bool ref_iszero(double a) { return a == 0; } bool ref_isnormal(double a) { return (a != 0) && !std::isinf(a) && !std::isnan(a); } int ref_sgn(double a) { return (a > 0) ? 1 : (a < 0) ? -1 : 0; } bool xf_iszero(const ExactFloat& xf) { return xf.is_zero(); } int xf_sgn(const ExactFloat& xf) { return xf.sgn(); } TEST_FN_VS_REF(bool, isnormal, ref_isnormal) TEST_FN_VS_REF(bool, xf_iszero, ref_iszero) TEST_FN_VS_REF(int, xf_sgn, ref_sgn) // Test a zero-argument ExactFloat member function against a corresponding // one-argument std:: function. #define TEST_FN_VS_STD_FN(ResultType, fn) \ ResultType ref_##fn(double a) { return std::fn(a); } \ TEST_FN_VS_REF(ResultType, fn, ref_##fn) TEST_FN_VS_STD_FN(bool, isinf) TEST_FN_VS_STD_FN(bool, isnan) TEST_FN_VS_STD_FN(bool, isfinite) TEST_FN_VS_STD_FN(bool, signbit) TEST(FpClassify, Nan) { EXPECT_EQ(fpclassify(ExactFloat(NAN)), FP_NAN); } TEST(FpClassify, Infinity) { EXPECT_EQ(fpclassify(ExactFloat(INFINITY)), FP_INFINITE); EXPECT_EQ(fpclassify(ExactFloat(-INFINITY)), FP_INFINITE); } TEST(FpClassify, Zero) { EXPECT_EQ(fpclassify(ExactFloat(0.0)), FP_ZERO); EXPECT_EQ(fpclassify(ExactFloat(std::copysign(0.0, -1.0))), FP_ZERO); } TEST(FpClassify, Normal) { EXPECT_EQ(fpclassify(ExactFloat(1.0)), FP_NORMAL); // Would be FP_INFINITE with double arg. EXPECT_EQ(fpclassify(2.0 * ExactFloat(std::numeric_limits::max())), FP_NORMAL); // Would be FP_SUBNORMAL with double arg. EXPECT_EQ(fpclassify(ExactFloat(std::numeric_limits::denorm_min())), FP_NORMAL); } typedef Vector2 MyVec2; typedef Vector3 MyVec3; TEST_F(ExactFloatTest, Vector3_Part1) { // Check that ExactFloat can be used with templatized classes such as Vector2 // and Vector3. We exercise all the methods of Vector3 to check that they // compile and do something reasonable. // // IsNaN() is not tested because it cannot be used with vectors of ExactFloats // (see the header file). // // This test is split into parts because of the stack frame size limit. MyVec3 zero; MyVec3 zero2(0, 0, 0); EXPECT_EQ(zero, zero2); MyVec3 zero3(MyVec2(0, 0), 0); EXPECT_EQ(zero, zero3); MyVec3 almost_zero(1e-200, 1e-100, 1e-50); EXPECT_NE(zero, almost_zero); EXPECT_TRUE(almost_zero.aequal(zero, 1e-15)); EXPECT_LT(zero, almost_zero); // Total order, for STL purposes. MyVec3 almost_zero2(ExactFloat(1e-320), 0, 0); EXPECT_NE(zero, almost_zero2); EXPECT_TRUE(almost_zero2.aequal(zero, 1e-300)); EXPECT_LT(almost_zero2, almost_zero); EXPECT_LT(zero, almost_zero2); EXPECT_EQ(MyVec3(1, -2, 3), MyVec3::Cast(Vector3_d(1, -2, 3))); EXPECT_EQ(MyVec3(1, -2, 3), MyVec3::Cast(Vector3(1, -2, 3))); // Two ways to convert, these are the same. MyVec3 x(1.5, 2.5, 3.5); Vector3_d y1 = Vector3_d::Cast(x); EXPECT_EQ(y1, Vector3_d(1.5, 2.5, 3.5)); Vector3_d y2 = Vector3_d(static_cast(x[0]), static_cast(x[1]), static_cast(x[2])); EXPECT_EQ(y2, Vector3_d(1.5, 2.5, 3.5)); } TEST_F(ExactFloatTest, Vector3_Part2) { MyVec3 x; x.Set(1, 2, 3.5); EXPECT_EQ(MyVec3(1, 2, 3.5), x); x = MyVec3(4, 5, 6); EXPECT_EQ(MyVec3(4, 5, 6), x); x += MyVec3(1, 2, 3); EXPECT_EQ(MyVec3(5, 7, 9), x); x -= MyVec3(3, 2, 1); EXPECT_EQ(MyVec3(2, 5, 8), x); x *= 3; EXPECT_EQ(MyVec3(6, 15, 24), x); x = MyVec3(2, 5, 8); MyVec3 y(1, 2, 3); MyVec3 z = x.MulComponents(y); EXPECT_EQ(MyVec3(2, 10, 24), z); z = MyVec3(1, 2, 3); EXPECT_EQ(MyVec3(5, 7, 9), z + MyVec3(4, 5, 6)); EXPECT_EQ(MyVec3(-5, -3, -1), z - MyVec3(6, 5, 4)); EXPECT_EQ(MyVec3(-1, -2, -3), -z); EXPECT_EQ(z.DotProd(z), 14); EXPECT_EQ(MyVec3(2, 4, 6), 2 * z); } TEST_F(ExactFloatTest, Vector3_Part3) { MyVec3 y(3, 4, 1); MyVec3 z(2, -3, 1); EXPECT_EQ(MyVec3(7, -1, -17), y.CrossProd(z)); EXPECT_EQ(3, y[0]); y[0] = 5; EXPECT_EQ(5, y.x()); EXPECT_EQ(4, y.y()); EXPECT_EQ(1, y.z()); y.x(3); EXPECT_EQ(MyVec3(3, 4, 1), y); ExactFloat* y_data = y.Data(); y_data[2] = 12; EXPECT_EQ(MyVec3(3, 4, 12), y); EXPECT_EQ(y.Data()[1], ExactFloat(4)); EXPECT_EQ(y.Norm2(), 169); EXPECT_EQ(6, z.DotProd(y)); EXPECT_EQ(2, y.LargestAbsComponent()); EXPECT_EQ(Vector3(1, 2, 0), z.ComponentOrder()); EXPECT_EQ(MyVec3(4, -6, 2), 2 * z); EXPECT_EQ(MyVec3(4, 9, 1), z.MulComponents(z)); EXPECT_EQ(MyVec3(2, 3, 1), z.Abs()); EXPECT_EQ(MyVec3(2, 3, 1), z.Fabs()); z.Set(-0.5, 1.5, 2.5); EXPECT_EQ(MyVec3(-1, 1, 2), z.Floor()); EXPECT_EQ(MyVec3(0, 2, 3), z.Ceil()); EXPECT_EQ(MyVec3(0, 2, 2), z.FRound()); EXPECT_EQ(Vector3_i(0, 2, 2), z.IRound()); y.Set(2.0, -2.0, 0.0); EXPECT_EQ(MyVec3(2.0, 1.5, 2.5), Max(z, y)); EXPECT_EQ(MyVec3(-0.5, -2.0, 0.0), Min(z, y)); y.Clear(); EXPECT_EQ(MyVec3(0, 0, 0), y); ABSL_LOG(INFO) << "Test of Vector3 stream output: " << y; } TEST_F(ExactFloatTest, Vector3_IsNaN_NoNaNsReturnsFalse) { EXPECT_FALSE(MyVec3(1, 2, 3).IsNaN()); } TEST_F(ExactFloatTest, Vector3_IsNaN_AnyNanReturnsTrue) { constexpr double kNaN = std::numeric_limits::quiet_NaN(); EXPECT_TRUE(MyVec3(kNaN, 2, 3).IsNaN()); EXPECT_TRUE(MyVec3(1, 2, kNaN).IsNaN()); } TEST_F(ExactFloatTest, ImplicitConversions) { // Check that constants are implicitly converted to ExactFloats when they are // used in arithmetic expressions. // Check that ints/doubles are converted to ExactFloats in comparisons. EXPECT_EQ(1, ExactFloat(1.0)); EXPECT_LE(1.5, ExactFloat(2.5)); // Check that ints/doubles can be used as the first argument in arithmetic // operations. ExactFloat x = 11; EXPECT_EQ(24, 13 + x); EXPECT_EQ(10.5, 21.5 - x); EXPECT_EQ(-22, 2.0 * -x); // Intrinsic where one argument is an ExactFloat and the other is an int. EXPECT_EQ(3.0, fmax(ExactFloat(1), 3)); } TEST_F(ExactFloatTest, ExactCalculations) { // Try a calculation that requires high precision. ExactFloat v1 = pow(2, 1000); ExactFloat v2 = v1 - pow(2, -1000); ExactFloat v3 = v1 + pow(2, -1000); EXPECT_EQ(v3 * v3 - v2 * v2, 4 * v1 * pow(2, -1000)); EXPECT_EQ((v3 + v2) * (v3 - v2), 4 * v1 * pow(2, -1000)); // Check that precision is increased as necessary to avoid rounding. typedef Vector3 Vector3_xf; Vector3_xf x(1.1e300, 1.1e-300, 1.1); Vector3_xf y(1.1, 1.1e300, 1.1e-300); Vector3_xf z(1.1e-300, 1.1, 1.1e300); ExactFloat det = x.CrossProd(y).DotProd(z); EXPECT_GE(det.prec(), 6000); EXPECT_LT(det.prec(), 6300); } void BM_Det3x3(benchmark::State &state) { // Compute the determinant of a 3x3 matrix of numbers in the range [0,1). // (It would be better to use a different matrix for each iteration, but // then generating the matrix takes up a significant fraction of the time.) typedef Vector3 Vector3_xf; std::mt19937_64 rnd; Vector3_d a(absl::Uniform(rnd, 0, 1), absl::Uniform(rnd, 0, 1), absl::Uniform(rnd, 0, 1)); Vector3_d b(absl::Uniform(rnd, 0, 1), absl::Uniform(rnd, 0, 1), absl::Uniform(rnd, 0, 1)); Vector3_d c(absl::Uniform(rnd, 0, 1), absl::Uniform(rnd, 0, 1), absl::Uniform(rnd, 0, 1)); for (auto _ : state) { Vector3_xf xa = Vector3_xf::Cast(a); Vector3_xf xb = Vector3_xf::Cast(b); Vector3_xf xc = Vector3_xf::Cast(c); ExactFloat det = xa.CrossProd(xb).DotProd(xc); ABSL_CHECK_NE(det.sgn(), 0); } } BENCHMARK(BM_Det3x3); } // namespace src/s2/util/math/exactfloat/exactfloat_underflow_test.cc000066400000000000000000000104641524103652300240240ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include #include "s2/util/math/exactfloat/exactfloat.h" namespace { using ::exactfloat::ExactFloat; TEST(ExactFloatTest, Overflow) { // Construct an ExactFloat whose exponent is kMaxExp. const int kMaxExp = ExactFloat::kMaxExp; ExactFloat v = ldexp(ExactFloat(0.5), kMaxExp); EXPECT_FALSE(isinf(v)); EXPECT_EQ(kMaxExp, v.exp()); // Now check that if the exponent is made larger, it overflows. EXPECT_TRUE(isinf(2 * v)); EXPECT_GT(2 * v, 0); EXPECT_TRUE(isinf(-2 * v)); EXPECT_LT(-2 * v, 0); // Check that overflowing the exponent a lot does not cause problems. EXPECT_TRUE(isinf(v * v)); } TEST(ExactFloatTest, OverflowMaxExpAndPrecision) { const int kMaxExp = ExactFloat::kMaxExp; const int kMaxPrec = ExactFloat::kMaxPrec; const int kMinExp = ExactFloat::kMinExp; // Now build an ExactFloat whose exponent and precision are both maximal (!) const ExactFloat v = ldexp(1.0 - ldexp(ExactFloat(1.0), -kMaxPrec), kMaxExp); EXPECT_FALSE(isinf(v)); EXPECT_EQ(ExactFloat::kMaxExp, v.exp()); EXPECT_EQ(ExactFloat::kMaxPrec, v.prec()); // Try overflowing it in various ways. EXPECT_TRUE( isinf(v + ldexp(ExactFloat(1.0), kMaxExp - kMaxPrec))); EXPECT_TRUE(isinf(2 * v)); // Check that if kMaxPrec is exceeded, the result is NaN. The first line // attempts to add one more bit to the mantissa, while the second line // attempts to add as many bits as possible (by adding together the largest // and smallest possible maximum-precision numbers). EXPECT_TRUE( isnan(v + ldexp(ExactFloat(1.0), kMaxExp - kMaxPrec - 1))); EXPECT_TRUE(isnan( v + ldexp(1.0 - ldexp(ExactFloat(1.0), -kMaxPrec), kMinExp))); // Check that if kMaxExp and kMaxPrec are exceeded simultaneously, the // result is infinity rather than NaN. ExactFloat a = ldexp(1.0 - ldexp(ExactFloat(1.0), -kMaxPrec), kMaxExp); ExactFloat b = ldexp(1.0 - ldexp(ExactFloat(1.0), -kMaxPrec), kMaxExp - 1); EXPECT_TRUE(isinf(a + b)); } TEST(ExactFloatTest, Underflow) { // Construct an ExactFloat whose exponent is kMinExp. const int kMinExp = ExactFloat::kMinExp; const ExactFloat v = ldexp(ExactFloat(0.5), kMinExp); EXPECT_FALSE(v.is_zero()); EXPECT_EQ(kMinExp, v.exp()); // Now check that if the exponent is made smaller, it underflows. EXPECT_TRUE((0.5 * v).is_zero()); EXPECT_FALSE(signbit(0.5 * v)); EXPECT_TRUE((-0.5 * v).is_zero()); EXPECT_TRUE(signbit(-0.5 * v)); // Check that underflowing the exponent a lot does not cause problems. EXPECT_TRUE((v * v).is_zero()); } // Skip this test for iOS* and Android because it times out constantly. #if !defined(__ANDROID__) && !defined(__APPLE__) TEST(ExactFloatTest, UnderflowMaxExpAndMinPrecision) { const int kMinExp = ExactFloat::kMinExp; const int kMaxPrec = ExactFloat::kMaxPrec; // Now build an ExactFloat whose exponent is minimal and whose precision is // maximal. const ExactFloat v = ldexp(1.0 - ldexp(ExactFloat(1.0), -kMaxPrec), kMinExp); EXPECT_FALSE(v.is_zero()); EXPECT_EQ(ExactFloat::kMinExp, v.exp()); EXPECT_EQ(ExactFloat::kMaxPrec, v.prec()); // Try underflowing it in various ways. ExactFloat underflow = 0.5 * v; EXPECT_TRUE(underflow.is_zero() && !signbit(underflow)); underflow = -0.5 * v; EXPECT_TRUE(underflow.is_zero() && signbit(underflow)); // Check that if kMaxPrec is exceeded, the result is NaN. EXPECT_TRUE(isnan(v + ldexp(ExactFloat(1.0), kMinExp + 1))); // Check that if kMinExp and kMaxPrec are exceeded simultaneously, the // result is zero rather than NaN. underflow = ldexp(v, -1); EXPECT_TRUE(underflow.is_zero() && !signbit(underflow)); underflow = ldexp(-v, -1); EXPECT_TRUE(underflow.is_zero() && signbit(underflow)); } #endif } // namespace src/s2/util/math/mathutil.cc000066400000000000000000000043261524103652300162430ustar00rootroot00000000000000// Copyright 2008 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // #include "s2/util/math/mathutil.h" #include #include bool MathUtil::RealRootsForCubic(long double const a, long double const b, long double const c, long double *const r1, long double *const r2, long double *const r3) { // According to Numerical Recipes (pp. 184-5), what // follows is an arrangement of computations to // compute the roots of a cubic that minimizes // roundoff error (as pointed out by A.J. Glassman). long double const a_squared = a * a, a_third = a / 3.0, b_tripled = 3.0 * b; long double const Q = (a_squared - b_tripled) / 9.0; long double const R = (2.0 * a_squared * a - 3.0 * a * b_tripled + 27.0 * c) / 54.0; long double const R_squared = R * R; long double const Q_cubed = Q * Q * Q; if (R_squared < Q_cubed) { long double const root_Q = sqrt(Q); long double const two_pi_third = 2.0 * M_PI / 3.0; long double const theta_third = acos(R / sqrt(Q_cubed)) / 3.0; long double const minus_two_root_Q = -2.0 * root_Q; *r1 = minus_two_root_Q * cos(theta_third) - a_third; *r2 = minus_two_root_Q * cos(theta_third + two_pi_third) - a_third; *r3 = minus_two_root_Q * cos(theta_third - two_pi_third) - a_third; return true; } long double const A = -sgn(R) * pow(std::abs(R) + sqrt(R_squared - Q_cubed), 1.0 / 3.0L); if (A != 0.0) { // in which case, B from NR is zero *r1 = A + Q / A - a_third; return false; } *r1 = *r2 = *r3 = -a_third; return true; } src/s2/util/math/mathutil.h000066400000000000000000000170061524103652300161040ustar00rootroot00000000000000// Copyright 2001 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // // This class is intended to contain a collection of useful (static) // mathematical functions, properly coded (by consulting numerical // recipes or another authoritative source first). #ifndef S2_UTIL_MATH_MATHUTIL_H_ #define S2_UTIL_MATH_MATHUTIL_H_ #include #include // Returns the sign of x: // -1 if x < 0, // +1 if x > 0, // 0 if x = 0, // unspecified if x is NaN. template inline T sgn(const T x) { return (x == 0 ? 0 : (x < 0 ? -1 : 1)); } class MathUtil { public: // Solves for the real roots of x^3+ax^2+bx+c=0, returns true iff // all three are real, in which case the roots are stored (in any // order) in r1, r2, r3; otherwise, exactly one real root exists and // it is stored in r1. static bool RealRootsForCubic(long double a, long double b, long double c, long double *r1, long double *r2, long double *r3); // -------------------------------------------------------------------- // Round // This function rounds a floating-point number to an integer. It // works for positive or negative numbers. // // Values that are halfway between two integers may be rounded up or // down, for example Round(0.5) == 0 and Round(1.5) == 2. // This allows the function to be implemented efficiently on Intel // processors (see the template specializations at the bottom of this // file). You should not use this function if you care about which // way such half-integers are rounded. // // Example usage: // double y, z; // int x = Round(y + 3.7); // int64_t b = Round(0.3 * z); // // Note that the floating-point template parameter is typically inferred // from the argument type, i.e. there is no need to specify it explicitly. // -------------------------------------------------------------------- template static IntOut Round(FloatIn x) { static_assert(!std::is_integral::value, "FloatIn is integer"); static_assert(std::is_integral::value, "IntOut is not integer"); // We don't use sgn(x) below because there is no need to distinguish the // (x == 0) case. Also note that there are specialized faster versions // of this function for Intel processors at the bottom of this file. return static_cast(x < 0 ? (x - 0.5) : (x + 0.5)); } // -------------------------------------------------------------------- // FastIntRound, FastInt64Round // Fast routines for converting floating-point numbers to integers. // // These routines are approximately 6 times faster than the default // implementation of Round on Intel processors (12 times faster on // the Pentium 3). They are also more than 5 times faster than simply // casting a "double" to an "int" using static_cast. This is // because casts are defined to truncate towards zero, which on Intel // processors requires changing the rounding mode and flushing the // floating-point pipeline (unless programs are compiled specifically // for the Pentium 4, which has a new instruction to avoid this). // // Numbers that are halfway between two integers may be rounded up or // down. This is because the conversion is done using the default // rounding mode, which rounds towards the closest even number in case // of ties. So for example, FastIntRound(0.5) == 0, but // FastIntRound(1.5) == 2. These functions should only be used with // applications that don't care about which way such half-integers are // rounded. // // There are template specializations of Round() which call these // functions (for "int" and "int64_t" only), but it's safer to call them // directly. // // This functions are equivalent to lrint() and llrint() as defined in // the ISO C99 standard. Unfortunately this standard does not seem to // widely adopted yet and these functions are not available by default. // -------------------------------------------------------------------- static int32_t FastIntRound(double x) { // This function is not templatized because gcc doesn't seem to be able // to deal with inline assembly code in templatized functions, and there // is no advantage to passing an argument type of "float" on Intel // architectures anyway. #if defined __GNUC__ && (defined __i386__ || defined __SSE2__) #if defined __SSE2__ // SSE2. int32_t result; __asm__ __volatile__ ("cvtsd2si %1, %0" : "=r" (result) // Output operand is a register : "x" (x)); // Input operand is an xmm register return result; #elif defined __i386__ // FPU stack. Adapted from /usr/include/bits/mathinline.h. int32_t result; __asm__ __volatile__ ("fistpl %0" : "=m" (result) // Output operand is a memory location : "t" (x) // Input operand is top of FP stack : "st"); // Clobbers (pops) top of FP stack return result; #endif // if defined __x86_64__ || ... #else return Round(x); #endif // if defined __GNUC__ && ... } static int64_t FastInt64Round(double x) { #if defined __GNUC__ && (defined __i386__ || defined __x86_64__) #if defined __x86_64__ // SSE2. int64_t result; __asm__ __volatile__ ("cvtsd2si %1, %0" : "=r" (result) // Output operand is a register : "x" (x)); // Input operand is an xmm register return result; #elif defined __i386__ // There is no CVTSD2SI in i386 to produce a 64 bit int, even with SSE2. // FPU stack. Adapted from /usr/include/bits/mathinline.h. int64_t result; __asm__ __volatile__ ("fistpll %0" : "=m" (result) // Output operand is a memory location : "t" (x) // Input operand is top of FP stack : "st"); // Clobbers (pops) top of FP stack return result; #endif // if defined __i386__ #else return Round(x); #endif // if defined __GNUC__ && ... } }; // ========================================================================= // #if (defined __i386__ || defined __x86_64__) && defined __GNUC__ // We define template specializations of Round() to get the more efficient // Intel versions when possible. Note that gcc does not currently support // partial specialization of templatized functions. template <> inline int32_t MathUtil::Round(double x) { return FastIntRound(x); } template <> inline int32_t MathUtil::Round(float x) { return FastIntRound(x); } template <> inline int64_t MathUtil::Round(double x) { return FastInt64Round(x); } template <> inline int64_t MathUtil::Round(float x) { return FastInt64Round(x); } #endif #endif // S2_UTIL_MATH_MATHUTIL_H_ src/s2/util/math/matrix3x3.h000066400000000000000000000446631524103652300161300ustar00rootroot00000000000000// Copyright 2003 Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // // A simple class to handle 3x3 matrices // The aim of this class is to be able to manipulate 3x3 matrices // and 3D vectors as naturally as possible and make calculations // readable. // For that reason, the operators +, -, * are overloaded. // (Reading a = a + b*2 - c is much easier to read than // a = Sub(Add(a, Mul(b,2)),c) ) // // Please be careful about overflows when using those matrices with integer types // The calculations are carried with VType. eg : if you are using uint8 as the // base type, all values will be modulo 256. // This feature is necessary to use the class in a more general framework with // VType != plain old data type. #ifndef S2_UTIL_MATH_MATRIX3X3_H_ #define S2_UTIL_MATH_MATRIX3X3_H_ #include #include #include #include "absl/log/absl_check.h" #include "s2/util/math/mathutil.h" #include "s2/util/math/vector.h" template class Matrix3x3 { private: VType m_[3][3]; public: typedef Matrix3x3 Self; typedef VType BaseType; typedef Vector3 MVector; // Initialize the matrix to 0 Matrix3x3() { m_[0][2] = m_[0][1] = m_[0][0] = VType(); m_[1][2] = m_[1][1] = m_[1][0] = VType(); m_[2][2] = m_[2][1] = m_[2][0] = VType(); } // Constructor explicitly setting the values of all the coefficient of // the matrix Matrix3x3(const VType &m00, const VType &m01, const VType &m02, const VType &m10, const VType &m11, const VType &m12, const VType &m20, const VType &m21, const VType &m22) { m_[0][0] = m00; m_[0][1] = m01; m_[0][2] = m02; m_[1][0] = m10; m_[1][1] = m11; m_[1][2] = m12; m_[2][0] = m20; m_[2][1] = m21; m_[2][2] = m22; } // Casting constructor template static Matrix3x3 Cast(const Matrix3x3 &mb) { return Matrix3x3(static_cast(mb(0, 0)), // static_cast(mb(0, 1)), // static_cast(mb(0, 2)), // static_cast(mb(1, 0)), // static_cast(mb(1, 1)), // static_cast(mb(1, 2)), // static_cast(mb(2, 0)), // static_cast(mb(2, 1)), // static_cast(mb(2, 2))); } // Change the value of all the coefficients of the matrix inline Matrix3x3 &Set(const VType &m00, const VType &m01, const VType &m02, const VType &m10, const VType &m11, const VType &m12, const VType &m20, const VType &m21, const VType &m22) { m_[0][0] = m00; m_[0][1] = m01; m_[0][2] = m02; m_[1][0] = m10; m_[1][1] = m11; m_[1][2] = m12; m_[2][0] = m20; m_[2][1] = m21; m_[2][2] = m22; return (*this); } // Matrix addition inline Matrix3x3 &operator+=(const Matrix3x3 &mb) { m_[0][0] += mb.m_[0][0]; m_[0][1] += mb.m_[0][1]; m_[0][2] += mb.m_[0][2]; m_[1][0] += mb.m_[1][0]; m_[1][1] += mb.m_[1][1]; m_[1][2] += mb.m_[1][2]; m_[2][0] += mb.m_[2][0]; m_[2][1] += mb.m_[2][1]; m_[2][2] += mb.m_[2][2]; return (*this); } // Matrix subtraction inline Matrix3x3 &operator-=(const Matrix3x3 &mb) { m_[0][0] -= mb.m_[0][0]; m_[0][1] -= mb.m_[0][1]; m_[0][2] -= mb.m_[0][2]; m_[1][0] -= mb.m_[1][0]; m_[1][1] -= mb.m_[1][1]; m_[1][2] -= mb.m_[1][2]; m_[2][0] -= mb.m_[2][0]; m_[2][1] -= mb.m_[2][1]; m_[2][2] -= mb.m_[2][2]; return (*this); } // Matrix multiplication by a scalar inline Matrix3x3 &operator*=(const VType &k) { m_[0][0] *= k; m_[0][1] *= k; m_[0][2] *= k; m_[1][0] *= k; m_[1][1] *= k; m_[1][2] *= k; m_[2][0] *= k; m_[2][1] *= k; m_[2][2] *= k; return (*this); } // Matrix addition inline Matrix3x3 operator+(const Matrix3x3 &mb) const { return Matrix3x3(*this) += mb; } // Matrix subtraction inline Matrix3x3 operator-(const Matrix3x3 &mb) const { return Matrix3x3(*this) -= mb; } // Change the sign of all the coefficients in the matrix friend inline Matrix3x3 operator-(const Matrix3x3 &vb) { return Matrix3x3(-vb.m_[0][0], -vb.m_[0][1], -vb.m_[0][2], // -vb.m_[1][0], -vb.m_[1][1], -vb.m_[1][2], // -vb.m_[2][0], -vb.m_[2][1], -vb.m_[2][2]); } // Matrix multiplication by a scalar inline Matrix3x3 operator*(const VType &k) const { return Matrix3x3(*this) *= k; } friend inline Matrix3x3 operator*(const VType &k, const Matrix3x3 &mb) { return Matrix3x3(mb) * k; } // Matrix multiplication inline Matrix3x3 operator*(const Matrix3x3 &mb) const { // clang-format off return Matrix3x3( m_[0][0] * mb.m_[0][0] + m_[0][1] * mb.m_[1][0] + m_[0][2] * mb.m_[2][0], m_[0][0] * mb.m_[0][1] + m_[0][1] * mb.m_[1][1] + m_[0][2] * mb.m_[2][1], m_[0][0] * mb.m_[0][2] + m_[0][1] * mb.m_[1][2] + m_[0][2] * mb.m_[2][2], m_[1][0] * mb.m_[0][0] + m_[1][1] * mb.m_[1][0] + m_[1][2] * mb.m_[2][0], m_[1][0] * mb.m_[0][1] + m_[1][1] * mb.m_[1][1] + m_[1][2] * mb.m_[2][1], m_[1][0] * mb.m_[0][2] + m_[1][1] * mb.m_[1][2] + m_[1][2] * mb.m_[2][2], m_[2][0] * mb.m_[0][0] + m_[2][1] * mb.m_[1][0] + m_[2][2] * mb.m_[2][0], m_[2][0] * mb.m_[0][1] + m_[2][1] * mb.m_[1][1] + m_[2][2] * mb.m_[2][1], m_[2][0] * mb.m_[0][2] + m_[2][1] * mb.m_[1][2] + m_[2][2] * mb.m_[2][2]); // clang-format on } // Multiplication of a matrix by a vector inline MVector operator*(const MVector &v) const { return MVector(m_[0][0] * v[0] + m_[0][1] * v[1] + m_[0][2] * v[2], m_[1][0] * v[0] + m_[1][1] * v[1] + m_[1][2] * v[2], m_[2][0] * v[0] + m_[2][1] * v[1] + m_[2][2] * v[2]); } // Return the determinant of the matrix inline VType Det() const { return m_[0][0] * m_[1][1] * m_[2][2] + m_[0][1] * m_[1][2] * m_[2][0] + m_[0][2] * m_[1][0] * m_[2][1] - m_[2][0] * m_[1][1] * m_[0][2] - m_[2][1] * m_[1][2] * m_[0][0] - m_[2][2] * m_[1][0] * m_[0][1]; } // Return the trace of the matrix inline VType Trace() const { return m_[0][0] + m_[1][1] + m_[2][2]; } // Return a pointer to the data array for interface with other libraries // like opencv VType *Data() { return reinterpret_cast(m_); } const VType *Data() const { return reinterpret_cast(m_); } // Return matrix element (i,j) with 0<=i<=2 0<=j<=2 inline VType &operator()(const int i, const int j) { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 3); ABSL_DCHECK_GE(j, 0); ABSL_DCHECK_LT(j, 3); return m_[i][j]; } inline VType operator()(const int i, const int j) const { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 3); ABSL_DCHECK_GE(j, 0); ABSL_DCHECK_LT(j, 3); return m_[i][j]; } // Return matrix element (i/3,i%3) with 0<=i<=8 (access concatenated rows). inline VType &operator[](const int i) { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 9); return reinterpret_cast(m_)[i]; } inline VType operator[](const int i) const { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 9); return reinterpret_cast(m_)[i]; } // Return the transposed matrix inline Matrix3x3 Transpose() const { return Matrix3x3(m_[0][0], m_[1][0], m_[2][0], // m_[0][1], m_[1][1], m_[2][1], // m_[0][2], m_[1][2], m_[2][2]); } // Return the transposed of the matrix of the cofactors // (Useful for inversion for example) inline Matrix3x3 ComatrixTransposed() const { return Matrix3x3(m_[1][1] * m_[2][2] - m_[2][1] * m_[1][2], m_[2][1] * m_[0][2] - m_[0][1] * m_[2][2], m_[0][1] * m_[1][2] - m_[1][1] * m_[0][2], m_[1][2] * m_[2][0] - m_[2][2] * m_[1][0], m_[2][2] * m_[0][0] - m_[0][2] * m_[2][0], m_[0][2] * m_[1][0] - m_[1][2] * m_[0][0], m_[1][0] * m_[2][1] - m_[2][0] * m_[1][1], m_[2][0] * m_[0][1] - m_[0][0] * m_[2][1], m_[0][0] * m_[1][1] - m_[1][0] * m_[0][1]); } // Matrix inversion inline Matrix3x3 Inverse() const { VType det = Det(); ABSL_CHECK_NE(det, VType(0)) << " Can't inverse. Determinant = 0."; return (VType(1) / det) * ComatrixTransposed(); } // Return the vector 3D at row i inline MVector Row(const int i) const { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 3); return MVector(m_[i][0], m_[i][1], m_[i][2]); } // Return the vector 3D at col i inline MVector Col(const int i) const { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 3); return MVector(m_[0][i], m_[1][i], m_[2][i]); } // Create a matrix from 3 row vectors static inline Matrix3x3 FromRows(const MVector &v1, const MVector &v2, const MVector &v3) { Matrix3x3 temp; temp.Set(v1[0], v1[1], v1[2], // v2[0], v2[1], v2[2], // v3[0], v3[1], v3[2]); return temp; } // Create a matrix from 3 column vectors static inline Matrix3x3 FromCols(const MVector &v1, const MVector &v2, const MVector &v3) { Matrix3x3 temp; temp.Set(v1[0], v2[0], v3[0], // v1[1], v2[1], v3[1], // v1[2], v2[2], v3[2]); return temp; } // Create a matrix from outer product of two vectors. static inline Matrix3x3 FromOuter(const MVector &ma, const MVector &mb) { Matrix3x3 m; for (int row = 0; row < 3; ++row) { m.SetRow(row, ma[row] * mb); } return m; } // Set the vector in row i to be v1 void SetRow(int i, const MVector &v1) { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 3); m_[i][0] = v1[0]; m_[i][1] = v1[1]; m_[i][2] = v1[2]; } // Set the vector in column i to be v1 void SetCol(int i, const MVector &v1) { ABSL_DCHECK_GE(i, 0); ABSL_DCHECK_LT(i, 3); m_[0][i] = v1[0]; m_[1][i] = v1[1]; m_[2][i] = v1[2]; } // Return a matrix M close to the original but verifying MtM = I // (useful to compensate for errors in a rotation matrix) Matrix3x3 Orthogonalize() const { MVector r1, r2, r3; r1 = Row(0).Normalize(); r2 = (Row(2).CrossProd(r1)).Normalize(); r3 = (r1.CrossProd(r2)).Normalize(); return FromRows(r1, r2, r3); } // Return the identity matrix static inline Matrix3x3 Identity() { Matrix3x3 temp; temp.Set(VType(1), VType(0), VType(0), // VType(0), VType(1), VType(0), // VType(0), VType(0), VType(1)); return temp; } // Return a matrix full of zeros static inline Matrix3x3 Zero() { return Matrix3x3(); } // Return a diagonal matrix with the coefficients in v static inline Matrix3x3 Diagonal(const MVector &v) { return Matrix3x3(v[0], VType(), VType(), // VType(), v[1], VType(), // VType(), VType(), v[2]); } // Return the matrix vvT static Matrix3x3 Sym3(const MVector &v) { return Matrix3x3(v[0] * v[0], v[0] * v[1], v[0] * v[2], // v[1] * v[0], v[1] * v[1], v[1] * v[2], // v[2] * v[0], v[2] * v[1], v[2] * v[2]); } // Return a matrix M such that: // for each u, M * u = v.CrossProd(u) static Matrix3x3 AntiSym3(const MVector &v) { return Matrix3x3(VType(), -v[2], v[1], // v[2], VType(), -v[0], // -v[1], v[0], VType()); } // Returns matrix that rotates |rot| radians around axis rot. static Matrix3x3 Rodrigues(const MVector &rot) { Matrix3x3 R; VType theta = rot.Norm(); MVector w = rot.Normalize(); Matrix3x3 Wv = Matrix3x3::AntiSym3(w); Matrix3x3 I = Matrix3x3::Identity(); Matrix3x3 A = Matrix3x3::Sym3(w); using std::cos; using std::sin; R = (1 - cos(theta)) * A + sin(theta) * Wv + cos(theta) * I; return R; } // Return a matrix that reflects a point across the plane defined by normal. static Matrix3x3 Householder(const MVector &normal) { MVector unit = normal.Normalize(); return Matrix3x3::Identity() - 2 * Matrix3x3::FromOuter(unit, unit); } // Returns v.Transpose() * (*this) * u VType MulBothSides(const MVector &v, const MVector &u) const { return ((*this) * u).DotProd(v); } // Use the 3x3 matrix as a projective transform for 2d points Vector2 Project(const Vector2 &v) const { MVector temp = (*this) * MVector(v[0], v[1], 1); return Vector2(temp[0] / temp[2], temp[1] / temp[2]); } // Return the Frobenius norm of the matrix: sqrt(sum(aij^2)) VType FrobeniusNorm() const { VType sum = VType(); for (int i = 0; i < 3; i++) { for (int j = 0; j < 3; j++) { sum += m_[i][j] * m_[i][j]; } } using std::sqrt; return sqrt(sum); } // Finds the eigen values of the matrix. Return the number of real eigenvalues // found. // If the matrix is known to be symmetric due to your problem formulation, // then please use SymmetricEigenSolver, since this method does not guarantee // finding all 3 real eigenvalues in pathological cases. See CL 49170250. int EigenValues(MVector *eig_val) const { long double r1, r2, r3; // NOLINT // characteristic polynomial // x^3 + a*x^2 + b*x + c VType a = -Trace(); VType b = m_[0][0] * m_[1][1] + m_[1][1] * m_[2][2] + m_[2][2] * m_[0][0] - m_[1][0] * m_[0][1] - m_[2][1] * m_[1][2] - m_[0][2] * m_[2][0]; VType c = -Det(); bool res = MathUtil::RealRootsForCubic(a, b, c, &r1, &r2, &r3); (*eig_val)[0] = r1; if (res) { (*eig_val)[1] = r2; (*eig_val)[2] = r3; return 3; } return 1; } // Finds the eigen values and optional associated eigen vectors of a // symmetric 3x3 matrix (not necessarily positive definite). // eigen values are sorted in decreasing order; // eig_val corresponds to the columns of the eig_vec matrix. // Note: The routine will only use the lower diagonal part // of the matrix, i.e. // | a00, | // | a10, a11, | // | a20, a21, a22 | void SymmetricEigenSolver(MVector *eig_val, Matrix3x3 *eig_vec /*nullable*/) const { // Compute characteristic polynomial coefficients. double c2 = -Trace(); double c1 = -(m_[1][0] * m_[1][0] - m_[0][0] * m_[1][1] - m_[0][0] * m_[2][2] - m_[1][1] * m_[2][2] + m_[2][0] * m_[2][0] + m_[2][1] * m_[2][1]); double c0 = -(m_[0][0] * m_[1][1] * m_[2][2] // - m_[2][0] * m_[2][0] * m_[1][1] // - m_[1][0] * m_[1][0] * m_[2][2] // - m_[0][0] * m_[2][1] * m_[2][1] // + 2 * m_[1][0] * m_[2][0] * m_[2][1]); // Root finding x^3 + c2*x^2 + c1*x + c0 = 0. // NOTE: Cannot reuse general cubic solver MathUtil::RealRootsForCubic() // because it doesn't guarantee finding 3 real roots, e.g. it won't always // return roots {2, 2, 0} for the cubic x^3 - 4*x^2 + 4*x + epsilon = 0. double q = (c2 * c2 - 3 * c1) / 9.0; double r = (2 * c2 * c2 * c2 - 9 * c2 * c1 + 27 * c0) / 54.0; // Assume R^2 <= Q^3 so there are three real roots. // Avoid sqrt of negative q, which can only happen due to numerical error. if (q < 0) q = 0; double sqrt_q = -2.0 * sqrt(q); double q3_r2 = q * q * q - r * r; // Avoid sqrt of negative q3_r2, which can only happen due to numerical // error. double theta = atan2(q3_r2 <= 0 ? 0 : sqrt(q3_r2), r); double c2_3 = c2 / 3; (*eig_val)[0] = sqrt_q * cos(theta / 3.0) - c2_3; (*eig_val)[1] = sqrt_q * cos((theta + 2.0 * M_PI) / 3.0) - c2_3; (*eig_val)[2] = sqrt_q * cos((theta - 2.0 * M_PI) / 3.0) - c2_3; // Sort eigen value in decreasing order Vector3 d_order = eig_val->ComponentOrder(); (*eig_val) = MVector((*eig_val)[d_order[2]], (*eig_val)[d_order[1]], (*eig_val)[d_order[0]]); // Compute eigenvectors if (!eig_vec) return; for (int i = 0; i < 3; ++i) { MVector r1, r2, r3, e1, e2, e3; r1[0] = m_[0][0] - (*eig_val)[i]; r2[0] = m_[1][0]; r3[0] = m_[2][0]; r1[1] = m_[1][0]; r2[1] = m_[1][1] - (*eig_val)[i]; r3[1] = m_[2][1]; r1[2] = m_[2][0]; r2[2] = m_[2][1]; r3[2] = m_[2][2] - (*eig_val)[i]; e1 = r1.CrossProd(r2); e2 = r2.CrossProd(r3); e3 = r3.CrossProd(r1); // Make e2 and e3 point in the same direction as e1 if (e2.DotProd(e1) < 0) e2 = -e2; if (e3.DotProd(e1) < 0) e3 = -e3; MVector e = (e1 + e2 + e3).Normalize(); eig_vec->SetCol(i, e); } } // Return true is one of the elements of the matrix is NaN bool IsNaN() const { for (int i = 0; i < 3; ++i) { for (int j = 0; j < 3; ++j) { if (isnan(m_[i][j])) { return true; } } } return false; } friend bool operator==(const Matrix3x3 &a, const Matrix3x3 &b) { return a.m_[0][0] == b.m_[0][0] && a.m_[0][1] == b.m_[0][1] && a.m_[0][2] == b.m_[0][2] && a.m_[1][0] == b.m_[1][0] && a.m_[1][1] == b.m_[1][1] && a.m_[1][2] == b.m_[1][2] && a.m_[2][0] == b.m_[2][0] && a.m_[2][1] == b.m_[2][1] && a.m_[2][2] == b.m_[2][2]; } friend bool operator!=(const Matrix3x3 &a, const Matrix3x3 &b) { return !(a == b); } friend std::ostream &operator<<(std::ostream &out, const Matrix3x3 &mb) { int i, j; for (i = 0; i < 3; i++) { if (i == 0) { out << "["; } else { out << " "; } for (j = 0; j < 3; j++) { out << mb(i, j) << " "; } if (i == 2) { out << "]"; } else { out << std::endl; } } return out; } template friend H AbslHashValue(H h, const Matrix3x3 &m) { return H::combine_contiguous(std::move(h), m.Data(), 3 * 3); } }; typedef Matrix3x3 Matrix3x3_i; typedef Matrix3x3 Matrix3x3_f; typedef Matrix3x3 Matrix3x3_d; #endif // S2_UTIL_MATH_MATRIX3X3_H_ src/s2/util/math/vector.h000066400000000000000000000460051524103652300155600ustar00rootroot00000000000000// Copyright Google Inc. All Rights Reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS-IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Simple classes to handle vectors in 2D, 3D, and 4D. // // Maintainers: Please be mindful of extreme degradations in unoptimized // performance here. #ifndef S2_UTIL_MATH_VECTOR_H_ #define S2_UTIL_MATH_VECTOR_H_ #include #include #include #include #include #include #include // NOLINT(readability/streams) #include #include #include #include "absl/log/absl_check.h" #include "absl/utility/utility.h" template class Vector2; template class Vector3; template class Vector4; namespace util { namespace math { namespace internal_vector { // CRTP base class for all Vector templates. template