/// <summary> /// Provides all of the unidirectional edges from the current H3Index. /// </summary> /// <param name="origin">The origin hexagon H3Index to find edges for.</param> /// <param name="edges">The memory to store all of the edges inside.</param> /// <!-- Based off 3.1.1 --> public static void getH3UnidirectionalEdgesFromHexagon(H3Index origin, List <H3Index> edges) { // Determine if the origin is a pentagon and special treatment needed. int isPentagon = H3Index.h3IsPentagon(origin); // This is actually quite simple. Just modify the bits of the origin // slightly for each direction, except the 'k' direction in pentagons, // which is zeroed. for (int i = 0; i < 6; i++) { if (isPentagon != 0 && i == 0) { edges[i] = H3Index.H3_INVALID_INDEX; } else { edges[i] = origin; var ei = edges[i]; H3Index.H3_SET_MODE(ref ei, Constants.H3_UNIEDGE_MODE); H3Index.H3_SET_RESERVED_BITS(ref ei, (ulong)i + 1); edges[i] = ei; } } }
/// <summary> /// Returns a unidirectional edge H3 index based on the provided origin and /// destination /// </summary> /// <param name="origin">The origin H3 hexagon index</param> /// <param name="destination">The destination H3 hexagon index</param> /// <returns>The unidirectional edge H3Index, or 0 on failure.</returns> /// <!-- Based off 3.1.1 --> public static H3Index getH3UnidirectionalEdge(H3Index origin, H3Index destination) { // Short-circuit and return an invalid index value if they are not neighbors if (h3IndexesAreNeighbors(origin, destination) == 0) { return(H3Index.H3_INVALID_INDEX); } // Otherwise, determine the IJK direction from the origin to the destination H3Index output = origin; H3Index.H3_SET_MODE(ref output, Constants.H3_UNIEDGE_MODE); // Checks each neighbor, in order, to determine which direction the // destination neighbor is located. Skips CENTER_DIGIT since that // would be this index. for (var direction = Direction.K_AXES_DIGIT; direction < Direction.NUM_DIGITS; direction++) { int rotations = 0; H3Index neighbor = Algos.h3NeighborRotations(origin, direction, ref rotations); if (neighbor == destination) { H3Index.H3_SET_RESERVED_BITS(ref output, (ulong)direction); return(output); } } // This should be impossible, return an invalid H3Index in this case; return(H3Index.H3_INVALID_INDEX); // LCOV_EXCL_LINE }
/// <summary> /// Returns the origin hexagon from the unidirectional edge H3Index /// </summary> /// <param name="edge">The edge H3 index</param> /// <returns>The origin H3 hexagon index</returns> /// <!-- Based off 3.1.1 --> public static H3Index getOriginH3IndexFromUnidirectionalEdge(H3Index edge) { if (H3Index.H3_GET_MODE(ref edge) != Constants.H3_UNIEDGE_MODE) { return(H3Index.H3_INVALID_INDEX); } H3Index origin = edge.value; H3Index.H3_SET_MODE(ref origin, Constants.H3_HEXAGON_MODE); H3Index.H3_SET_RESERVED_BITS(ref origin, 0); return(origin); }
/// <summary> /// Produces an index for ijk+ coordinates anchored by an origin. /// /// The coordinate space used by this function may have deleted /// regions or warping due to pentagonal distortion. /// /// Failure may occur if the coordinates are too far away from the origin /// or if the index is on the other side of a pentagon. /// </summary> /// <param name="origin">An anchoring index for the ijk+ coordinate system.</param> /// <param name="ijk">IJK+ Coordinates to find the index of</param> /// <param name="out_h3">The index will be placed here on success</param> /// <returns>0 on success, or another value on failure</returns> /// <!-- Based off 3.2.0 --> internal static int localIjkToH3(H3Index origin, CoordIJK ijk, ref H3Index out_h3) { int res = H3Index.H3_GET_RESOLUTION(origin); int originBaseCell = H3Index.H3_GET_BASE_CELL(origin); int originOnPent = BaseCells._isBaseCellPentagon(originBaseCell) ? 1 : 0; // This logic is very similar to faceIjkToH3 // initialize the index out_h3 = H3Index.H3_INIT; H3Index.H3_SET_MODE(ref out_h3, Constants.H3_HEXAGON_MODE); H3Index.H3_SET_RESOLUTION(ref out_h3, res); Direction dir; // check for res 0/base cell if (res == 0) { if (ijk.i > 1 || ijk.j > 1 || ijk.k > 1) { // out of range input return(1); } dir = CoordIJK._unitIjkToDigit(ref ijk); int newBaseCell = BaseCells._getBaseCellNeighbor(originBaseCell, dir); if (newBaseCell == BaseCells.INVALID_BASE_CELL) { // Moving in an invalid direction off a pentagon. return(1); } H3Index.H3_SET_BASE_CELL(ref out_h3, newBaseCell); return(0); } // we need to find the correct base cell offset (if any) for this H3 index; // start with the passed in base cell and resolution res ijk coordinates // in that base cell's coordinate system CoordIJK ijkCopy = new CoordIJK(ijk.i, ijk.j, ijk.k); // build the H3Index from finest res up // adjust r for the fact that the res 0 base cell offsets the indexing // digits for (int r = res - 1; r >= 0; r--) { CoordIJK lastIJK = ijkCopy; CoordIJK lastCenter; if (H3Index.isResClassIII(r + 1)) { // rotate ccw CoordIJK._upAp7(ref ijkCopy); lastCenter = ijkCopy; CoordIJK._downAp7(ref lastCenter); } else { // rotate cw CoordIJK._upAp7r(ref ijkCopy); lastCenter = ijkCopy; CoordIJK._downAp7r(ref lastCenter); } CoordIJK diff = new CoordIJK(); CoordIJK._ijkSub(ref lastIJK, ref lastCenter, ref diff); CoordIJK._ijkNormalize(ref diff); H3Index.H3_SET_INDEX_DIGIT(ref out_h3, r + 1, (ulong)CoordIJK._unitIjkToDigit(ref diff)); } // ijkCopy should now hold the IJK of the base cell in the // coordinate system of the current base cell if (ijkCopy.i > 1 || ijkCopy.j > 1 || ijkCopy.k > 1) { // out of range input return(2); } // lookup the correct base cell dir = CoordIJK._unitIjkToDigit(ref ijkCopy); int baseCell = BaseCells._getBaseCellNeighbor(originBaseCell, dir); // If baseCell is invalid, it must be because the origin base cell is a // pentagon, and because pentagon base cells do not border each other, // baseCell must not be a pentagon. int indexOnPent = (baseCell == BaseCells.INVALID_BASE_CELL ? 0 : BaseCells._isBaseCellPentagon(baseCell) ? 1 : 0); if (dir != (int)Direction.CENTER_DIGIT) { // If the index is in a warped direction, we need to unwarp the base // cell direction. There may be further need to rotate the index digits. int pentagonRotations = 0; if (originOnPent != 0) { Direction originLeadingDigit = H3Index._h3LeadingNonZeroDigit(origin); pentagonRotations = PENTAGON_ROTATIONS_REVERSE[(int)originLeadingDigit, (int)dir]; for (int i = 0; i < pentagonRotations; i++) { dir = CoordIJK._rotate60ccw(dir); } // The pentagon rotations are being chosen so that dir is not the // deleted direction. If it still happens, it means we're moving // into a deleted subsequence, so there is no index here. if (dir == Direction.K_AXES_DIGIT) { return(3); } baseCell = BaseCells._getBaseCellNeighbor(originBaseCell, dir); // indexOnPent does not need to be checked again since no pentagon // base cells border each other. if (baseCell == BaseCells.INVALID_BASE_CELL) { throw new Exception("assert(baseCell != BaseCells.INVALID_BASE_CELL);"); } if (BaseCells._isBaseCellPolarPentagon(baseCell)) { throw new Exception("assert(!BaseCells._isBaseCellPentagon(baseCell));"); } } // Now we can determine the relation between the origin and target base // cell. int baseCellRotations = BaseCells.baseCellNeighbor60CCWRots[originBaseCell, (int)dir]; if (baseCellRotations < 0) { throw new Exception("assert(baseCellRotations >= 0);"); } // Adjust for pentagon warping within the base cell. The base cell // should be in the right location, so now we need to rotate the index // back. We might not need to check for errors since we would just be // double mapping. if (indexOnPent != 0) { Direction revDir = BaseCells._getBaseCellDirection(baseCell, originBaseCell); if (revDir == Direction.INVALID_DIGIT) { throw new Exception("assert(revDir != Direction.INVALID_DIGIT);"); } // Adjust for the different coordinate space in the two base cells. // This is done first because we need to do the pentagon rotations // based on the leading digit in the pentagon's coordinate system. for (int i = 0; i < baseCellRotations; i++) { out_h3 = H3Index._h3Rotate60ccw(ref out_h3); } Direction indexLeadingDigit = H3Index._h3LeadingNonZeroDigit(out_h3); if (BaseCells._isBaseCellPolarPentagon(baseCell)) { pentagonRotations = PENTAGON_ROTATIONS_REVERSE_POLAR[(int)revDir, (int)indexLeadingDigit]; } else { pentagonRotations = PENTAGON_ROTATIONS_REVERSE_NONPOLAR[(int)revDir, (int)indexLeadingDigit]; } if (pentagonRotations < 0) { throw new Exception("assert(pentagonRotations >= 0);"); } for (int i = 0; i < pentagonRotations; i++) { out_h3 = H3Index._h3RotatePent60ccw(ref out_h3); } } else { if (pentagonRotations < 0) { throw new Exception("assert(pentagonRotations >= 0);"); } for (int i = 0; i < pentagonRotations; i++) { out_h3 = H3Index._h3Rotate60ccw(ref out_h3); } // Adjust for the different coordinate space in the two base cells. for (int i = 0; i < baseCellRotations; i++) { out_h3 = H3Index._h3Rotate60ccw(ref out_h3); } } } else if (originOnPent != 0 && indexOnPent != 0) { int originLeadingDigit = (int)H3Index._h3LeadingNonZeroDigit(origin); int indexLeadingDigit = (int)H3Index._h3LeadingNonZeroDigit(out_h3); int withinPentagonRotations = PENTAGON_ROTATIONS_REVERSE[originLeadingDigit, indexLeadingDigit]; if (withinPentagonRotations < 0) { throw new Exception("assert(withinPentagonRotations >= 0);"); } for (int i = 0; i < withinPentagonRotations; i++) { out_h3 = H3Index._h3Rotate60ccw(ref out_h3); } } if (indexOnPent != 0) { // TODO: There are cases in h3ToLocalIjk which are failed but not // accounted for here - instead just fail if the recovered index is // invalid. if (H3Index._h3LeadingNonZeroDigit(out_h3) == Direction.K_AXES_DIGIT) { return(4); } } H3Index.H3_SET_BASE_CELL(ref out_h3, baseCell); return(0); }