Request

Response

    Interpreting sun analysis results

    Background on the sun analysis can also be found in the Autodesk Forma help centre.

    For sun results, the grid is a Uint8Array and each sample point is represented with 30 Uint8 values.

    Each of the 8 bits in the Uint8 signals if the location is sunlit (1) or not (0) at a certain time.

    Results are provided for every 6 minutes throughout the day, which is why 30 bytes are required to represent the results for each sample point:

    24 hours * 10 measurements per hour = 240 bits = (240 / 8) bytes = 30 bytes.

    This table illustrates which time stamps the bits of the Uint8 for a point represents:

    Time 00:00 00:06 00:12 00:18 00:24 00:30 00:36 00:42 00:48 00:54 ... 23:48 23:54
    Time index [0 - 239] 0 1 2 3 4 5 6 7 8 9 ... 238 239
    Byte index [0 - 29] 0 0 0 0 0 0 0 0 1 1 ... 29 29
    Bit position [0 - 7] 7 6 5 4 3 2 1 0 7 6 ... 1 0

    As an example: if the first byte if the grid is 10101010, it would mean that the first point is sunlit at: 00:00, 00:12, 00:24, 00:36, while it is shaded at 00:06, 00:18, 00:30, 00:42.

    A few examples of possible Uint8 values and what they represent:

    Uint8BitsExplanation
    255 1111 1111 Point is sunlit at all the 8 corresponding points in time
    0 0000 0000 Point is in shadow all of the 8 corresponding points in time
    3 0000 0011 Point is sunlit the last two of the 8 corresponding points in time

    As we’re using the 30 bits packing for each sample point, we add a mask which denotes if each sample point is a valid sample point.

    Code example: Sunlit points at 13:00

    If you have followed the examples above and fetched a raw ground result as sunGroundGrid, the following code example illustrates how to generate a mask of sunlit sample points at 13:00:

    const N_SAMPLES_PER_HOUR = 10;
    const BITS_PER_BYTE = 8;
    const N_BYTES_PER_POINT = 30;
    const N_POINTS = sunGroundGrid.mask.length;
    
    // Find index corresponding to 13:00
    const timeIndex = 13 * N_SAMPLES_PER_HOUR; // = 130
    
    // Find the index of the byte containing the result for 13:00
    const byteIndex = Math.floor(timeIndex / BITS_PER_BYTE); // = 16
    
    // Find the position of the bit in the byte that represents 13:00
    const bitPosition = BITS_PER_BYTE - (timeIndex % BITS_PER_BYTE) - 1; // = 5
    
    function isKthBitSet(number, k) {
      return (number & (1 << k)) > 0;
    }
    
    const sunlitPointsMask = new Float32Array(N_POINTS).fill(NaN);
    for (let i = 0; i < N_POINTS; i++) {
      if (sunGroundGrid.mask[i]) {
        const scoresForPoint = sunGroundGrid.grid.slice(
          i * N_BYTES_PER_POINT,
          (i + 1) * N_BYTES_PER_POINT
        );
        // Extract the relevant byte and check if the corresponding bit is set
        sunlitPointsMask[i] = isKthBitSet(scoresForPoint[byteIndex], bitPosition);
      }
    }
    
    Show More