image operation image::imageops => add vertical-gradient

[foresterre]

introduced in image 0.23.9, #569

Thank you for taking the time to look at this feature request. If you want to help by implementing the feature, thanks!; I've added some ideas on how to implement it below. If there are questions, always feel free to ask!

PR 1:

• Create an issue for this step, e.g. titled Image Operation engine: add vertical-gradient

• Implement vertical-gradient operation

  • Add an ImgOp for the operation:

    sic/components/sic_image_engine/src/lib.rs

    Line 16 in 33acebf

    pub enum ImgOp {

  • Implement the operation:

    sic/components/sic_image_engine/src/engine.rs

    Line 110 in 33acebf

    fn process_operation(&mut self, operation: &ImgOp) -> Result<(), SicImageEngineError> {

  • Add tests to verify the operation works as expected. You can use the examples set by other operations. Consider using parameterized tests for similar test cases; the dependency should already exist.

PR 2 part 1:

• Create an issue for this step, e.g. titled Image Operation parsing: add vertical-gradient

• Consider syntax which works for both cli ops and the --apply-operations script. This means that an operation should be able to be parseable without introducing ambiguity with both the the Pest parser used for apply-operations script, as well as the cli ops parser used for the cli interface. Additionally, this last syntax should also be compatible with Clap, which is used for the general cli interface (but is inconvenient for the cli ops). The next points will describe the exact steps to implement these parsers. I would recommend doing both in one go to ensure compatibility with each other. You may consider dividing the actual work to multiple PR's, but doing so is optional.

PR 2 part 2:

• Implement cli ops and --apply-operations script parsers

• cli ops:

  • Add an OperationId for the operation:

    sic/components/sic_cli_ops/src/operations.rs

    Line 18 in 33acebf

    pub enum OperationId {

  • Implement takes_number_of_arguments:

    sic/components/sic_cli_ops/src/operations.rs

    Line 66 in 33acebf

    pub fn takes_number_of_arguments(self) -> usize {

  • Implement create_instruction:

    sic/components/sic_cli_ops/src/operations.rs

    Line 113 in 33acebf

    let stmt = match self {

    • To recognise values, we used the ParseInputsFromIter, which will be re-usable when implementing the Pest parser in part 3. Whether you should add a new type and implementation depends on the arguments required for the operation. If the operation arguments are complex, you can use a wrapper (example, instead of an argument tuple or primitive type.

PR 2 part 3:

• --apply-operations script:
  • Add operation to Pest:

    sic/components/sic_parser/src/grammar.pest

    Line 76 in 33acebf

    operation = _{

  • Add a Rule for the operation to the Pest PEG file:

    sic/components/sic_parser/src/grammar.pest

    Line 36 in 33acebf

    blur = ${ ^"blur" ~ WHITESPACE ~ fp }

  • Match the Rule you just made against the Instrs, and transform the Pest Pair(s) to the ImgOp you added at the start of this issue (This ImgOp is wrapped in by the Instr enum):

    sic/components/sic_parser/src/rule_parser.rs

    Line 26 in 33acebf

    pub fn parse_image_operations(pairs: Pairs<'_, Rule>) -> Result<Vec<Instr>, SicParserError> {

    . Here you can re-use the value parser used in part 2.
  • Add tests to verify parsing works as expected. You can use the examples set by other operations. Consider using parameterized tests for similar test cases; the dependency should already exist.